Initial commit: KavCorp infrastructure documentation
- CLAUDE.md: Project configuration for Claude Code - docs/: Infrastructure documentation - INFRASTRUCTURE.md: Service map, storage, network - CONFIGURATIONS.md: Service configs and credentials - CHANGELOG.md: Change history - DECISIONS.md: Architecture decisions - TASKS.md: Task tracking - scripts/: Automation scripts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
131
docs/traefik-ssl-setup.md
Normal file
131
docs/traefik-ssl-setup.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user