Tag 11: Reverse Proxy und TLS
Ziel: Ein Caddy-Proxy nimmt als einziger Dienst HTTPS-Verbindungen an, mit einer eigenen lokalen CA, die du exportierst und mit
curl --cacertprüfst. · Dauer: ca. 75 min · Voraussetzung: Tag 10
Briefing
- Neuer Dienst
proxymit Caddy: kein Docker-Socket nötig, eine kleine Konfigurationsdatei, TLS ohne öffentliche Domain. tls internallässt Caddy eine eigene CA anlegen (Root und Intermediate) und damit Zertifikate fürnotes.localhostausstellen.- Das
Caddyfilekommt alsconfigs:in den Container (Tag 4), CA und Zertifikate liegen im Volumecaddy_data. - web verliert seinen Port; von außen erreichbar sind nur noch proxy und (für Tests) api.
Mac Netz frontend Netz backend
:8443 ─HTTPS─┐
├─► proxy ──► web:3000 ──► api:8080 ──────► db:5432
:8000 ─HTTP──┘ (308) ▲
:8080 ─────────────────────────────────────┘ (nur für Drills und Tests)
Drill 1: Das Caddyfile
Tagesstart, Stack von Tag 10 abräumen, Stand von Tag 10 holen:
source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag11 && cd ~/compose-lab/tag11
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag10/notes/." .
docker pull -q caddy:2.11.7-alpineDas Caddyfile beschreibt pro Adresse („Site”) einen Block. Caddy
erwartet Tabs zum Einrücken; caddy fmt würde Leerzeichen
bemängeln.
mkdir -p proxy
cat > proxy/Caddyfile <<'EOF'
{
skip_install_trust
}
notes.localhost {
tls internal
encode gzip
header {
Strict-Transport-Security "max-age=31536000"
X-Content-Type-Options "nosniff"
-Server
}
reverse_proxy web:3000
}
EOF| Zeile | Wirkung |
|---|---|
skip_install_trust |
keine Installation der Root in einen Trust-Store |
tls internal |
Zertifikat von der eigenen CA statt per ACME (Let’s Encrypt) |
encode gzip |
Antworten komprimieren, wenn der Client es anbietet |
header { … } |
Security-Header setzen, -Server entfernt den
Server-Header |
reverse_proxy web:3000 |
alles an web weiterreichen (DNS im Netz frontend) |
Der Block ganz oben ohne Namen enthält globale Optionen. Ohne
skip_install_trust versucht Caddy beim ersten Zertifikat,
die Root ins System zu installieren – im Container sinnlos.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Dienst proxy
Zwei Änderungen in compose.yaml: web verliert seine
ports:, und der neue Dienst proxy kommt dazu.
Die vollständige Datei liegt in
code/tag11/notes/compose.yaml.
web:
# … wie an Tag 10, aber ohne ports: …
networks: [frontend]
proxy:
<<: *hardening
image: caddy:2.11.7-alpine
cap_add: [NET_BIND_SERVICE]
tmpfs: [/tmp]
ports:
- "127.0.0.1:${HTTPS_PORT:-8443}:443"
- "127.0.0.1:${HTTP_PORT:-8000}:80"
configs:
- source: caddyfile
target: /etc/caddy/Caddyfile
volumes:
- caddy_data:/data
- caddy_config:/config
networks: [frontend]
depends_on:
web:
condition: service_healthy
restart: unless-stoppedUnd unten bei den Top-Level-Einträgen:
volumes:
pgdata: {}
caddy_data: {}
caddy_config: {}
configs:
db_init:
file: ./db/init/10-readonly.sql
caddyfile:
file: ./proxy/CaddyfileVor dem Start prüft Caddy selbst die Datei – run
veröffentlicht keine Ports und startet mit --no-deps nichts
anderes mit:
docker compose run --rm --no-deps proxy caddy validate --config /etc/caddy/Caddyfile \
2>&1 | tail -1
docker compose up -d --wait
docker compose ps --format 'table {{.Service}}\t{{.Status}}\t{{.Ports}}'Erwartet (gekürzt, IDs und Zeiten weichen bei dir ab):
Valid configuration
Container notes-web-1 Healthy
Container notes-proxy-1 Starting
Container notes-proxy-1 Started
…
Container notes-proxy-1 Healthy
SERVICE STATUS PORTS
api Up 3 seconds (healthy) 127.0.0.1:8080->8080/tcp
db Up 6 seconds (healthy) 5432/tcp
proxy Up Less than a second 443/udp, 2019/tcp, 127.0.0.1:8000->80/tcp, …
web Up 2 seconds (healthy) 3000/tcp
worker Up 2 seconds
proxy startet erst, wenn web gesund ist. Er hat keinen Healthcheck;
für --wait zählt deshalb „läuft”. 443/udp
(HTTP/3) und 2019/tcp (Admin-API) stehen nur als
EXPOSE im Image, veröffentlicht sind allein die beiden
Ports auf 127.0.0.1.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Härtung und eine Capability
proxy erbt per <<: *hardening
cap_drop: [ALL], read_only und
no-new-privileges (Tag 9). Warum steht trotzdem
cap_add: [NET_BIND_SERVICE] darin? Nimm die Zeile
vorübergehend heraus:
sed -i.bak 's/^ cap_add: \[NET_BIND_SERVICE\]/ # &/' compose.yaml
docker compose up -d proxy >/dev/null 2>&1
sleep 20
docker compose ps -a proxy --format 'table {{.Service}}\t{{.Status}}'
docker compose logs --no-log-prefix proxy | uniq -c
docker compose run --rm --no-deps --entrypoint getcap proxy /usr/bin/caddyErwartet (gekürzt, Zahlen weichen ab):
SERVICE STATUS
proxy Restarting (255) 6 seconds ago
8 exec /usr/bin/caddy: operation not permitted
/usr/bin/caddy cap_net_bind_service=ep
Das Programm selbst trägt eine File-Capability, damit es auch ohne root Port 80 und 443 öffnen darf. Fehlt diese Capability in der Bounding-Menge des Containers, verweigert der Kernel schon den Start des Programms – Caddy kommt nicht einmal bis zu seiner ersten Logzeile. Zurück zum Original:
mv compose.yaml.bak compose.yaml
docker compose up -d --wait >/dev/null 2>&1
docker compose exec proxy grep CapEff /proc/1/statusErwartet:
CapEff: 0000000000000400
0x400 ist Bit 10, CAP_NET_BIND_SERVICE –
die einzige Capability, die Caddy hat.
Achtung: Ohne Healthcheck kann
up --waiteinen Container, der gerade in einer Neustart-Schleife hängt, kurz als „Healthy” melden. Für Dienste, die du per--waitabnimmst, lohnt ein echter Healthcheck oder ein Blick inps -a.
Fortschritt speichern? Kostenlos registrieren
Drill 4: TLS mit der eigenen CA prüfen
*.localhost zeigt nach RFC 6761 immer auf die eigene
Maschine; curl löst den Namen selbst auf. --resolve macht
die Zuordnung trotzdem ausdrücklich und funktioniert mit jedem
Namen.
curl -sS --resolve notes.localhost:8443:127.0.0.1 https://notes.localhost:8443/healthz
echo "Exit: $?"Erwartet:
curl: (60) SSL certificate problem: unable to get local issuer certificate
…
Exit: 60
Richtig so: curl kennt die CA von Caddy nicht. Sie liegt im Volume
unter /data/caddy/pki/authorities/local/.
docker compose cp holt die öffentliche Root – nur die, der
private Schlüssel root.key bleibt im Volume:
docker compose exec -T proxy ls /data/caddy/pki/authorities/local/
printf '%s\n' '# Lokale CA von Caddy (Tag 11)' 'proxy/root.crt' >> .gitignore
docker compose cp proxy:/data/caddy/pki/authorities/local/root.crt proxy/root.crt
openssl x509 -in proxy/root.crt -noout -subject -enddate
curl -sS --resolve notes.localhost:8443:127.0.0.1 --cacert proxy/root.crt \
https://notes.localhost:8443/healthz; echoErwartet (gekürzt, Zeiten weichen ab):
intermediate.crt
intermediate.key
root.crt
root.key
notes-proxy-1 Copied notes-proxy-1:/data/caddy/pki/authorities/local/root.crt to …
subject=CN=Caddy Local Authority - 2026 ECC Root
notAfter=Sep 6 22:26:30 2036 GMT
ok
Echtes TLS, echte Prüfung, keine Ausnahme mit -k.
proxy/root.crt kommt vorher in .gitignore
(printf im Block): Die Root gehört zu genau diesem Volume.
Jetzt das Zertifikat der Site:
echo | openssl s_client -connect 127.0.0.1:8443 -servername notes.localhost \
2>/dev/null | openssl x509 -noout -issuer -ext subjectAltName -dates
curl -sS --cacert proxy/root.crt https://localhost:8443/healthz; echo "Exit: $?"Erwartet (gekürzt):
issuer=CN=Caddy Local Authority - ECC Intermediate
X509v3 Subject Alternative Name: critical
DNS:notes.localhost
notBefore=Oct 29 22:26:30 2026 GMT
notAfter=Oct 30 10:26:30 2026 GMT
curl: (35) LibreSSL/3.3.6: error:1404B438:SSL routines:…:tlsv1 alert internal error
Exit: 35
- Das Blatt-Zertifikat stellt die Intermediate aus,
nicht die Root. Es gilt 12 Stunden (Standard von
tls internal); Caddy erneuert es selbst. - Für einen Namen ohne Site-Block (hier
localhost) hat Caddy kein Zertifikat und bricht den Handshake ab.
Fortschritt speichern? Kostenlos registrieren
Drill 5: HTTP leitet um, Header und gzip
curl -sS -i --resolve notes.localhost:8000:127.0.0.1 http://notes.localhost:8000/healthzErwartet (gekürzt):
HTTP/1.1 308 Permanent Redirect
Connection: close
Location: https://notes.localhost/healthz
Server: Caddy
Caddy leitet automatisch mit 308 auf HTTPS um, aber
auf Port 443: Den veröffentlichten Port 8443 kennt Caddy nicht. In
Produktion mit 80/443 passt das, im Labor zeigt der Redirect ins Leere –
das löst die Challenge. Die Umleitung antwortet außerdem noch mit
Server: Caddy, denn header gilt nur im
Site-Block auf HTTPS.
Für die nächsten Befehle eine kleine Shell-Funktion:
c() { curl -sS --resolve notes.localhost:8443:127.0.0.1 --cacert proxy/root.crt "$@"; }
c -I https://notes.localhost:8443/Erwartet (gekürzt):
HTTP/2 200
alt-svc: h3=":443"; ma=2592000
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000
via: 1.1 Caddy
x-content-type-options: nosniff
x-powered-by: Express
content-length: 273
- HTTP/2 ist mit TLS automatisch an. Der
server-Header fehlt, dafür nenntviaden Proxy. x-powered-by: Expressverrät noch die Technik dahinter. Mit-X-Powered-Byimheader-Block wäre auch das weg.
Ob encode gzip greift, siehst du an einer größeren
Antwort. Lege ein paar Notizen über den Proxy an – web hängt den Key
selbst an:
for i in 1 2 3 4 5 6 7 8; do
c -o /dev/null -w '%{http_code} ' -X POST https://notes.localhost:8443/api/notes \
-H 'Content-Type: application/json' -d "{\"text\":\"Notiz $i über HTTPS\"}"
done; echo
for enc in identity gzip; do
c -o /dev/null -D - -w "$enc: %{size_download} Bytes\n" -H "Accept-Encoding: $enc" \
https://notes.localhost:8443/api/notes | grep -i -E 'content-encoding|Bytes'
doneErwartet (Größen weichen ab):
201 201 201 201 201 201 201 201
identity: 766 Bytes
content-encoding: gzip
gzip: 341 Bytes
Kleine Antworten wie index.html (273 Bytes) bleiben
unkomprimiert, Caddy lässt sie unter einer Mindestgröße aus.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Pfad-Routing web und api
Ein Proxy kann nach Pfaden verteilen. Ändere das Caddyfile
vorübergehend: alles unter /v1/ geht ans
API, /v1/metrics bleibt gesperrt, der Rest an web.
cp proxy/Caddyfile proxy/Caddyfile.tag11
cat > proxy/Caddyfile <<'EOF'
{
skip_install_trust
}
notes.localhost {
tls internal
encode gzip
header {
Strict-Transport-Security "max-age=31536000"
X-Content-Type-Options "nosniff"
-Server
}
handle /v1/metrics {
respond "forbidden" 403
}
handle_path /v1/* {
reverse_proxy api:8080
}
handle {
reverse_proxy web:3000
}
}
EOF
docker compose exec proxy caddy reload --config /etc/caddy/Caddyfile 2>/dev/null
echo "Exit: $?"Erwartet:
Exit: 0
handle-Blöcke schließen sich gegenseitig aus, der
spezifischere Pfad gewinnt. handle_path schneidet das
Präfix ab: Aus /v1/version wird beim API
/version. caddy reload lädt die Datei über die
Admin-API im Container neu – ohne Neustart und ohne abgebrochene
Verbindungen.
for p in /v1/version /v1/notes /v1/metrics /api/notes; do
printf '%-12s %s\n' "$p" "$(c -o /dev/null -w '%{http_code}' \
"https://notes.localhost:8443$p")"
done
c -X POST https://notes.localhost:8443/v1/notes -H 'Content-Type: application/json' \
-d '{"text":"direkt ans API"}' -w '%{http_code}\n'Erwartet:
/v1/version 200
/v1/notes 200
/v1/metrics 403
/api/notes 200
{"error":"invalid api key"}
401
Über /v1/ gilt die Regel des API selbst: POST nur mit
X-API-Key. Die Metriken bleiben intern – Prometheus holt
sie morgen direkt im Netz (Tag 12). Jetzt zurück zum Stand von heute,
und achte darauf, was up dazu sagt:
cp proxy/Caddyfile.tag11 proxy/Caddyfile && rm proxy/Caddyfile.tag11
docker compose up -d --wait 2>&1 | grep proxy
c -o /dev/null -w '%{http_code}\n' https://notes.localhost:8443/v1/metrics
docker compose exec proxy caddy reload --config /etc/caddy/Caddyfile 2>/dev/null
c -o /dev/null -w '%{http_code}\n' https://notes.localhost:8443/v1/metricsErwartet:
Container notes-proxy-1 Running
Container notes-proxy-1 Waiting
Container notes-proxy-1 Healthy
403
404
Compose sieht keine Änderung am Dienst und lässt den Container
laufen. Die Datei im Container ist zwar schon neu (configs:
mit file: ist ein Bind-Mount), aber Caddy arbeitet mit der
geladenen Fassung weiter, bis du reload aufrufst. Danach
landet /v1/metrics wieder bei web, und das kennt den Pfad
nicht.
Achtung: Ein Bind-Mount einer einzelnen Datei hängt am Inode. Editoren, die beim Speichern eine neue Datei anlegen und umbenennen, ändern die Datei im Container nicht. Dann hilft nur
docker compose up -d --force-recreate proxy.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Die CA lebt im Volume
docker compose up -d --wait --force-recreate proxy >/dev/null 2>&1
c https://notes.localhost:8443/healthz; echo
docker compose rm -sf proxy >/dev/null 2>&1
docker volume rm notes_caddy_data
docker compose up -d --wait proxy >/dev/null 2>&1
c https://notes.localhost:8443/healthz; echo "Exit: $?"Erwartet:
ok
notes_caddy_data
curl: (60) SSL certificate problem: unable to get local issuer certificate
…
Exit: 60
Ein neuer Container mit demselben Volume behält die CA, ein neues
Volume bringt eine neue CA – und jede verteilte root.crt
wird wertlos. Gleiches passiert mit docker compose down -v.
Root neu holen:
docker compose cp proxy:/data/caddy/pki/authorities/local/root.crt proxy/root.crt \
>/dev/null 2>&1
c https://notes.localhost:8443/healthz; echoErwartet:
ok
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Der Stack läuft (docker compose up -d --wait). Den
vollständigen Stand findest du in code/tag11/notes/. proxy
läuft, web veröffentlicht keinen Port:
cd ~/compose-lab/tag11
docker compose ps --format '{{.Service}} {{.Ports}}'Erwartet (gekürzt):
api 127.0.0.1:8080->8080/tcp
db 5432/tcp
proxy 443/udp, 2019/tcp, 127.0.0.1:8000->80/tcp, 127.0.0.1:8443->443/tcp
web 3000/tcp
worker
HTTPS mit der eigenen CA:
curl -s --resolve notes.localhost:8443:127.0.0.1 --cacert proxy/root.crt \
https://notes.localhost:8443/healthz; echoErwartet:
ok
HTTP leitet um:
curl -s -o /dev/null -w '%{http_code}\n' --resolve notes.localhost:8000:127.0.0.1 \
http://notes.localhost:8000/Erwartet:
308
HSTS gesetzt, kein Server-Header (nur eine Zeile):
curl -s -o /dev/null -D - --resolve notes.localhost:8443:127.0.0.1 \
--cacert proxy/root.crt https://notes.localhost:8443/ | grep -iE '^(strict|server)'Erwartet:
strict-transport-security: max-age=31536000
Die Root-CA steht in .gitignore:
grep -x 'proxy/root.crt' .gitignoreErwartet:
proxy/root.crt
Challenge
Sorg dafür, dass
curl -L http://notes.localhost:8000/healthz bis zur Antwort
ok durchkommt, ohne die Ports auf dem Mac zu ändern.
compose.yaml und proxy/Caddyfile bleiben
unverändert; schreib eine zusätzliche Compose-Datei.
Hinweis: Caddy hängt einen Port an die Umleitung,
wenn die Site-Adresse selbst einen Port nennt, und das Caddyfile kennt
Umgebungsvariablen als {$NAME:standard}.
Lösung
Caddy lauscht im Container auf demselben Port, den der Mac
veröffentlicht. Ein eigenes Caddyfile und eine Override-Datei mit
!override (Tag 7):
cat > proxy/Caddyfile.ports <<'EOF'
{
skip_install_trust
}
notes.localhost:{$HTTPS_PORT:8443} {
tls internal
encode gzip
header {
Strict-Transport-Security "max-age=31536000"
X-Content-Type-Options "nosniff"
-Server
}
reverse_proxy web:3000
}
EOF
cat > compose.ports.yaml <<'EOF'
# compose.ports.yaml – Challenge Tag 11: Redirect auf den veröffentlichten HTTPS-Port
services:
proxy:
environment:
HTTPS_PORT: ${HTTPS_PORT:-8443}
ports: !override
- "127.0.0.1:${HTTPS_PORT:-8443}:${HTTPS_PORT:-8443}"
- "127.0.0.1:${HTTP_PORT:-8000}:80"
configs: !override
- source: caddyfile_ports
target: /etc/caddy/Caddyfile
configs:
caddyfile_ports:
file: ./proxy/Caddyfile.ports
EOF
docker compose -f compose.yaml -f compose.ports.yaml up -d --wait proxy >/dev/null 2>&1
docker compose ps proxy --format '{{.Ports}}'
curl -sS -i --resolve notes.localhost:8000:127.0.0.1 \
http://notes.localhost:8000/healthz | grep -i location
curl -sS -L --resolve notes.localhost:8000:127.0.0.1 \
--resolve notes.localhost:8443:127.0.0.1 --cacert proxy/root.crt \
http://notes.localhost:8000/healthz; echoErwartet:
443/tcp, 2019/tcp, 443/udp, 127.0.0.1:8443->8443/tcp, 127.0.0.1:8000->80/tcp
Location: https://notes.localhost:8443/healthz
ok
Ein Port allein in https_port (globale Option) hilft
übrigens nicht: Caddy lässt den Port im Redirect weg, wenn er dem
konfigurierten HTTPS-Port entspricht, weil es davon ausgeht, dass davor
eine Weiterleitung von 443 sitzt (live geprüft). cap_add
bleibt trotz hohem Port nötig – die File-Capability aus Drill 3 hängt am
Programm, nicht am Port. Die Dateien liegen unter
code/tag11/challenge/. Zurück zum Stand des Tages:
docker compose up -d --wait >/dev/null 2>&1
docker compose ps proxy --format '{{.Ports}}'
docker compose downErwartet:
443/udp, 2019/tcp, 127.0.0.1:8000->80/tcp, 127.0.0.1:8443->443/tcp
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- In Produktion kommen Zertifikate per ACME (Let’s Encrypt, oder eine
interne ACME-CA wie step-ca, Vault/OpenBao PKI) – Caddy kann beides;
tls internalist für Labor und interne Testumgebungen. - Die Root einer internen CA verteilt das Plattform-Team per
Konfigurationsmanagement in die Trust-Stores (Betriebssystem, Java,
Container-Images), nicht per
curl --cacert. caddy_dataenthält private Schlüssel: Backup verschlüsselt, Zugriff wie auf Secrets. Geht das Volume verloren, ist jede verteilte Root wertlos (Drill 7).- Traefik ist die verbreitete Alternative mit Docker-Labels als Konfiguration. Sein Docker-Provider braucht den Docker-Socket – nur über einen Socket-Proxy mit Lesezugriff, nie direkt (Tag 9).
- Der Proxy ist die Stelle für Rate-Limits, Zugriffsschutz für
/metricsund Admin- Pfade sowie Zugriffslogs; HSTS erst mit langermax-ageundincludeSubDomainsausrollen, wenn alle Subdomains HTTPS können.