# Traefik SSL/TLS Setup with Namecheap

**Last Updated**: 2025-11-16

## Configuration Summary

Traefik is configured to use Let's Encrypt with DNS-01 challenge via Namecheap for wildcard SSL certificates.

### Environment Variables

Located in: `/etc/systemd/system/traefik.service.d/override.conf` (inside Traefik LXC 104)

```bash
NAMECHEAP_API_USER=kavren
NAMECHEAP_API_KEY=8156f3d9ef664c91b95f029dfbb62ad5
NAMECHEAP_PROPAGATION_TIMEOUT=3600  # 1 hour timeout for DNS propagation
NAMECHEAP_POLLING_INTERVAL=30        # Check every 30 seconds
NAMECHEAP_TTL=300                    # 5 minute TTL for DNS records
```

### Traefik Configuration

File: `/etc/traefik/traefik.yaml`

```yaml
certificatesResolvers:
  letsencrypt:
    acme:
      email: cory.bailey87@gmail.com
      storage: /etc/traefik/ssl/acme.json
      dnsChallenge:
        provider: namecheap
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"
```

### Wildcard Certificate

Configured for:
- Main domain: `kavcorp.com`
- Wildcard: `*.kavcorp.com`

## Namecheap API Requirements

1. **API Access Enabled**: Must have API access enabled in Namecheap account
2. **IP Whitelisting**: Public IP `99.74.188.161` must be whitelisted
3. **API Key**: Must have valid API key with DNS modification permissions

### Verifying API Access

Test Namecheap API from Traefik LXC:
```bash
pct exec 104 -- curl -s 'https://api.namecheap.com/xml.response?ApiUser=kavren&ApiKey=8156f3d9ef664c91b95f029dfbb62ad5&UserName=kavren&Command=namecheap.domains.getList&ClientIp=99.74.188.161'
```

## Existing Certificates

Valid Let's Encrypt certificates already obtained:
- `traefik.kavcorp.com`
- `sonarr.kavcorp.com`
- `radarr.kavcorp.com`

Stored in: `/etc/traefik/ssl/acme.json`

## Troubleshooting

### Common Issues

**DNS Propagation Timeout**:
- Error: "propagation: time limit exceeded"
- Solution: Increased `NAMECHEAP_PROPAGATION_TIMEOUT` to 3600 seconds (1 hour)

**API Authentication Failed**:
- Verify IP whitelisted: 99.74.188.161
- Verify API key is correct
- Check API access is enabled in Namecheap

**Deprecated Configuration Warning**:
- Fixed: Removed deprecated `delayBeforeCheck` option
- Now using default propagation settings controlled by environment variables

### Monitoring Certificate Generation

Check Traefik logs:
```bash
ssh pm2 "pct exec 104 -- tail -f /var/log/traefik/traefik.log"
```

Filter for ACME/certificate errors:
```bash
ssh pm2 "pct exec 104 -- cat /var/log/traefik/traefik.log | grep -i 'acme\|certificate\|error'"
```

### Manual Certificate Renewal

Certificates auto-renew. To force renewal:
```bash
# Delete acme.json and restart Traefik (will regenerate all certs)
ssh pm2 "pct exec 104 -- rm /etc/traefik/ssl/acme.json && systemctl restart traefik"
```

**WARNING**: Only do this if necessary, as Let's Encrypt has rate limits!

## Certificate Request Flow

1. New service added to `/etc/traefik/conf.d/*.yaml`
2. Traefik detects new route requiring HTTPS
3. Checks if certificate exists in acme.json
4. If not, initiates DNS-01 challenge:
   - Creates TXT record via Namecheap API: `_acme-challenge.subdomain.kavcorp.com`
   - Waits for DNS propagation (up to 1 hour)
   - Polls DNS servers every 30 seconds
   - Let's Encrypt verifies TXT record
   - Certificate issued and stored in acme.json
5. Certificate served for HTTPS connections

## Next Steps

When adding new services:
1. Add route configuration to `/etc/traefik/conf.d/media-services.yaml` (or create new file)
2. Traefik will automatically request certificate on first HTTPS request
3. Monitor logs for any DNS propagation issues
4. Certificate will be cached and auto-renewed before expiration

## Notes

- Traefik v3.6.1 in use
- DNS-01 challenge allows wildcard certificates
- Certificates valid for 90 days, auto-renewed at 60 days
- Rate limit: 50 certificates per domain per week (Let's Encrypt)