Zum Inhalt springen
Trainingslager IT-Trainingslager

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 --cacert prüfst. · Dauer: ca. 75 min · Voraussetzung: Tag 10

Briefing

  • Neuer Dienst proxy mit Caddy: kein Docker-Socket nötig, eine kleine Konfigurationsdatei, TLS ohne öffentliche Domain.
  • tls internal lässt Caddy eine eigene CA anlegen (Root und Intermediate) und damit Zertifikate für notes.localhost ausstellen.
  • Das Caddyfile kommt als configs: in den Container (Tag 4), CA und Zertifikate liegen im Volume caddy_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-alpine

Das 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-stopped

Und 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/Caddyfile

Vor 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/caddy

Erwartet (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/status

Erwartet:

CapEff: 0000000000000400

0x400 ist Bit 10, CAP_NET_BIND_SERVICE – die einzige Capability, die Caddy hat.

Achtung: Ohne Healthcheck kann up --wait einen Container, der gerade in einer Neustart-Schleife hängt, kurz als „Healthy” melden. Für Dienste, die du per --wait abnimmst, lohnt ein echter Healthcheck oder ein Blick in ps -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; echo

Erwartet (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/healthz

Erwartet (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 nennt via den Proxy.
  • x-powered-by: Express verrät noch die Technik dahinter. Mit -X-Powered-By im header-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'
done

Erwartet (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/metrics

Erwartet:

 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; echo

Erwartet:

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; echo

Erwartet:

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' .gitignore

Erwartet:

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; echo

Erwartet:

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 down

Erwartet:

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 internal ist 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_data enthä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 /metrics und Admin- Pfade sowie Zugriffslogs; HSTS erst mit langer max-age und includeSubDomains ausrollen, wenn alle Subdomains HTTPS können.