michaelschiemer/docs/SSL_DEPLOYMENT.md

SSL/TLS Deployment Guide

Vollständige Anleitung für Let's Encrypt SSL/TLS Setup im Custom PHP Framework.

Übersicht

Das Framework nutzt Let's Encrypt mit einem Certbot Sidecar Container für automatische SSL-Zertifikatsverwaltung.

Architektur:

┌─────────────────────────────────────────────────────────┐
│  Nginx Container (macbre/nginx-http3)                   │
│  • HTTP/3 & QUIC Support                                │
│  • TLS 1.3 & TLS 1.2                                    │
│  • Security Headers                                      │
│  • Shared Volume: /etc/letsencrypt (read-only)          │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ Shared Volumes
                   ↓
┌─────────────────────────────────────────────────────────┐
│  Certbot Sidecar Container (certbot/certbot)            │
│  • Auto-renewal every 12h                               │
│  • HTTP-01 Challenge via webroot                        │
│  • Shared Volume: /etc/letsencrypt (read-write)         │
└─────────────────────────────────────────────────────────┘

Voraussetzungen

1. Domain konfiguriert: DNS A-Record zeigt auf Server-IP
2. Firewall: Port 80 und 443 offen
3. Docker & Docker Compose installiert
4. Production Environment konfiguriert

Initial Setup

1. Environment Configuration

# Kopiere Production Template
cp .env.production.example .env.production

# Bearbeite .env.production
nano .env.production

Wichtige Variablen:

DOMAIN_NAME=michaelschiemer.de
SSL_EMAIL=mail@michaelschiemer.de
LETSENCRYPT_ENABLED=true
APP_ENV=production
APP_DEBUG=false

2. SSL Zertifikat Initial Holen

# Führe SSL Initialization Script aus
./scripts/ssl-init.sh

# Mit Custom Domain und Email
./scripts/ssl-init.sh yourdomain.com admin@yourdomain.com

# Testing Mode (Staging Certificates - empfohlen für ersten Test)
LETSENCRYPT_STAGING=1 ./scripts/ssl-init.sh

Das Script macht:

1. Startet Nginx Container
2. Erstellt ACME Challenge Verzeichnis
3. Holt Let's Encrypt Zertifikat via HTTP-01
4. Speichert Zertifikate in Docker Volume
5. Startet Nginx mit SSL neu

3. Production Stack Starten

# Starte kompletten Production Stack
docker-compose -f docker-compose.yml -f docker-compose.production.yml up -d

# Check Logs
docker-compose -f docker-compose.yml -f docker-compose.production.yml logs -f web certbot

SSL Testing & Validation

Lokaler Test

# Führe SSL Test Script aus
./scripts/ssl-test.sh

# Mit Custom Domain
./scripts/ssl-test.sh yourdomain.com

Test Prüft:

• ✅ Port 443 Erreichbarkeit
• ✅ Zertifikatsgültigkeit
• ✅ Let's Encrypt Issuer
• ✅ TLS 1.3 & TLS 1.2 Support
• ✅ HTTP → HTTPS Redirect
• ✅ HSTS Header
• ✅ Security Headers

Online SSL Tests

SSL Labs (A+ Rating anstreben):

https://www.ssllabs.com/ssltest/analyze.html?d=michaelschiemer.de

Mozilla Observatory:

https://observatory.mozilla.org/analyze/michaelschiemer.de

Security Headers:

https://securityheaders.com/?q=michaelschiemer.de

Auto-Renewal

Certbot Sidecar Container

Der Certbot Container läuft permanent und prüft alle 12 Stunden ob Zertifikate erneuert werden müssen.

# Check Certbot Logs
docker logs certbot

# Manuelles Renewal testen (Dry-Run)
docker exec certbot certbot renew --dry-run

# Manuelles Renewal (falls nötig)
docker exec certbot certbot renew

# Nginx nach Manual Renewal neu laden
docker-compose restart web

Renewal Monitoring

Zertifikats-Ablaufdatum prüfen:

# Via Script
./scripts/ssl-test.sh

# Manuell
docker exec certbot certbot certificates

Empfohlene Monitoring-Strategie:

• Certbot Logs täglich checken
• Alert wenn Zertifikat < 30 Tage gültig
• Automatisches Monitoring via Cron/SystemD Timer

Troubleshooting

Problem: Zertifikat kann nicht geholt werden

Symptom: ssl-init.sh schlägt fehl

Ursachen & Lösungen:

1. DNS nicht korrekt:

# DNS prüfen
dig michaelschiemer.de
nslookup michaelschiemer.de

# Warte bis DNS propagiert ist (kann 1-48h dauern)

2. Port 80 nicht erreichbar:

# Firewall prüfen
sudo ufw status
sudo ufw allow 80
sudo ufw allow 443

# Nginx Test
curl -I http://michaelschiemer.de/.well-known/acme-challenge/test

3. ACME Challenge Location fehlt:

# Nginx Config prüfen
docker exec web nginx -t

# Log prüfen
docker logs web

Problem: Zertifikat wird nicht erneuert

Symptom: Certbot Renewal schlägt fehl

Lösungen:

1. Certbot Logs prüfen:

docker logs certbot
docker exec certbot certbot renew --dry-run --verbose

2. Webroot Permissions:

# Permissions prüfen
docker exec web ls -la /var/www/certbot/.well-known/acme-challenge/

3. Nginx Config Syntax:

docker exec web nginx -t

Problem: HTTPS funktioniert nicht nach Renewal

Symptom: Alte Zertifikate werden verwendet

Lösung:

# Nginx neu laden
docker-compose restart web

# Oder ohne Downtime
docker exec web nginx -s reload

Zero-Downtime Renewal

Nginx unterstützt graceful reload ohne Connection-Drops:

# Reload ohne Downtime
docker exec web nginx -s reload

# In Auto-Renewal integrieren
docker exec certbot certbot renew --post-hook "nginx -s reload"

Production Best Practices

1. Monitoring Setup

Cron Job für tägliche Checks:

# /etc/cron.daily/ssl-check
#!/bin/bash
/path/to/scripts/ssl-test.sh michaelschiemer.de > /var/log/ssl-check.log 2>&1

# Alert wenn weniger als 30 Tage
DAYS_LEFT=$(docker exec certbot certbot certificates | grep "VALID:" | awk '{print $6}' | head -1)
if [ "$DAYS_LEFT" -lt "30" ]; then
    echo "WARNING: SSL certificate expires in $DAYS_LEFT days" | mail -s "SSL Alert" admin@michaelschiemer.de
fi

2. Backup Strategy

Zertifikate Backup:

# Backup Let's Encrypt Config
docker run --rm \
  -v certbot-conf:/etc/letsencrypt \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/letsencrypt-$(date +%Y%m%d).tar.gz /etc/letsencrypt

# Restore
docker run --rm \
  -v certbot-conf:/etc/letsencrypt \
  -v $(pwd)/backups:/backup \
  alpine tar xzf /backup/letsencrypt-20241220.tar.gz -C /

3. Security Hardening

HTTP/3 aktivieren (bereits konfiguriert):

listen 443 quic reuseport;
http3 on;
add_header Alt-Svc 'h3=":443"; ma=86400';

HSTS Preload (nach 6 Monaten stabiler Betrieb):

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

Dann einreichen bei: https://hstspreload.org/

Makefile Integration

Füge zu Makefile hinzu:

# SSL Certificate Management
ssl-init: ## Initialize Let's Encrypt certificates
	./scripts/ssl-init.sh

ssl-test: ## Test SSL configuration
	./scripts/ssl-test.sh

ssl-renew: ## Manually renew certificates
	docker exec certbot certbot renew
	docker-compose restart web

ssl-status: ## Check certificate status
	docker exec certbot certbot certificates

Verwendung:

make ssl-init    # Initial Setup
make ssl-test    # Test SSL
make ssl-renew   # Manual Renewal
make ssl-status  # Check Expiry

Migration von Self-Signed zu Let's Encrypt

Wenn du von Self-Signed Zertifikaten migrierst:

# 1. Backup alte Zertifikate
cp -r docker/nginx/ssl docker/nginx/ssl.backup

# 2. SSL Init ausführen
./scripts/ssl-init.sh

# 3. Nginx Config Update (automatisch via docker-compose.production.yml)
# 4. Stack neu starten
docker-compose -f docker-compose.yml -f docker-compose.production.yml restart

Kosten

Let's Encrypt: ✅ Kostenlos

• Unlimitierte Zertifikate
• Automatische Renewal
• Wildcard-Zertifikate möglich (DNS-01 Challenge)

Rate Limits:

• 50 Zertifikate pro Domain pro Woche
• 5 Duplicate Certificates pro Woche
• Kein Problem für normale Production-Nutzung

Support & Dokumentation

Let's Encrypt Dokumentation: https://letsencrypt.org/docs/ Certbot Dokumentation: https://eff-certbot.readthedocs.io/ Framework SSL Issues: https://github.com/yourusername/framework/issues

Zusammenfassung

Setup-Schritte:

1. ✅ .env.production konfigurieren
2. ✅ ./scripts/ssl-init.sh ausführen
3. ✅ Production Stack starten
4. ✅ ./scripts/ssl-test.sh validieren
5. ✅ SSL Labs Test (A+ Rating)

Auto-Renewal: ✅ Certbot Container erneuert automatisch

Zero-Downtime: ✅ Nginx reload ohne Connection-Drops

Production-Ready: ✅ HTTP/3, TLS 1.3, Security Headers