proxmox-infra/docs/traefik-ssl-setup.md

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)

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

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:

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:

ssh pm2 "pct exec 104 -- tail -f /var/log/traefik/traefik.log"

Filter for ACME/certificate errors:

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:

# 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)