Hinatadocs

Reverse Proxy & TLS

Hinata stellt auf dem Host zwei reine HTTP-Dienste bereit:

  • die Web-App auf HINATA_APP_PORT (Standard 3456)
  • die API auf HINATA_PORT (Standard 3356)

In Produktion legst du diese Ports nie direkt offen. Ein Reverse Proxy terminiert TLS und leitet die Anfragen an die Container weiter.

Empfohlen sind zwei Subdomains:

SubdomainZweckWeiterleitung an
track.example.comFlutter-Web-Apphost:3456 (HINATA_APP_PORT)
api.track.example.comREST-API + SSEhost:3356 (HINATA_PORT)

Warum zwei Subdomains

Die Web-App ruft die API cross-origin auf. Mit getrennten Hostnamen bleibt CORS explizit, du kannst beides getrennt skalieren oder cachen, und es passt zu den Vorgaben aus .env.example (HINATA_BASE_URL / HINATA_WEB_BASE_URL).

Unten findest du fertige Konfigurationen für nginx, Caddy und Traefik.

Vorab: drei Einstellungen, die zusammenpassen müssen

Setze diese Werte am Hinata-Server-Container, egal welchen Proxy du nutzt (siehe Konfigurationsreferenz):

# Öffentliche URLs, die der Server bekannt gibt (JWT-Issuer, E-Mail-Deeplinks, SSO-Redirects)
HINATA_BASE_URL=https://api.track.example.com
HINATA_WEB_BASE_URL=https://track.example.com

# Browser-Origins, die die API cross-origin aufrufen dürfen: MUSS die Web-App enthalten
HINATA_CORS_ALLOWED_ORIGINS=https://track.example.com

# CIDR(s) deines Reverse Proxy, damit der Server X-Forwarded-* von ihm vertraut
HINATA_TRUSTED_PROXIES=172.16.0.0/12

HINATA_TRUSTED_PROXIES korrekt setzen, sonst kein Rate-Limiting pro Client

Hinata liest die echte Client-IP aus X-Forwarded-For nur, wenn der direkte Gegenpart in HINATA_TRUSTED_PROXIES liegt. Ist der Wert leer, wird niemandem vertraut, und alle Anfragen scheinen vom Proxy zu kommen.

Rate-Limiting (HINATA_RATE_LIMIT_*) und die Login-Sperre gegen Brute Force hängen an der Client-IP. Ein falscher Wert heißt deshalb ein gemeinsamer Zähler für das ganze Internet. Entweder werden alle gemeinsam gedrosselt, oder ein gefälschter X-Forwarded-For umgeht das Limit.

Trag die Adresse des Proxy ein, wie der Container sie sieht (meist das Docker-Bridge-Subnetz, z. B. 172.16.0.0/12). Nicht die öffentliche IP.

Die Adresse steht in den Serverlogs, oder du fragst das Netzwerk ab:

docker network inspect hinata_hinata \
  --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'

Der Server liest X-Forwarded-For von rechts und überspringt jede Adresse aus HINATA_TRUSTED_PROXIES. Die erste Adresse, die nicht dazugehört, ist der Client. Was ein Client weiter links in den Header schreibt, zählt also nicht. Kommt X-Forwarded-For von einem Gegenpart, dem der Server nicht vertraut, schreibt er das einmal ins Log, und Adminbereich › Moderation zeigt einen Tag lang eine Warnung. Daran erkennst du, dass der Wert fehlt oder falsch ist.

HSTS ist bereits erledigt

Der Server sendet selbst Strict-Transport-Security, CSP und Referrer-Policy. HSTS musst du im Proxy nicht ergänzen. TLS und die Zertifikatserneuerung übernimmt der Proxy.

nginx + Let's Encrypt (certbot)

Hol zuerst Zertifikate für beide Hostnamen. Dann nutzt du die Server-Blöcke unten.

Zertifikate holen

sudo certbot certonly --nginx \
  -d track.example.com \
  -d api.track.example.com

Certbot richtet den Erneuerungs-Timer selbst ein. Testen kannst du ihn mit sudo certbot renew --dry-run.

Server-Blöcke

# --- Alles von HTTP auf HTTPS umleiten --------------------------------------
server {
    listen 80;
    listen [::]:80;
    server_name track.example.com api.track.example.com;
    return 301 https://$host$request_uri;
}

# --- Web-App: track.example.com  →  host:3456 -------------------------------
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name track.example.com;

    ssl_certificate     /etc/letsencrypt/live/track.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/track.example.com/privkey.pem;

    # Flutter-Web kann große canvaskit/wasm-Assets ausliefern
    client_max_body_size 25m;

    location / {
        proxy_pass http://127.0.0.1:3456;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
    }
}

# --- API: api.track.example.com  →  host:3356 -------------------------------
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name api.track.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.track.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.track.example.com/privkey.pem;

    # Anhänge werden hierhin hochgeladen: an dein ENV-Attachment-Limit anpassen
    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:3356;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
    }

    # --- Server-Sent Events (Live-Attachment-Sync) --------------------------
    # SSE-Verbindungen bleiben offen; Pufferung deaktivieren und lange
    # Read-Timeouts nutzen, sonst kommen Events nur schubweise oder brechen ab.
    location ~ ^/api/v1/.*/stream$ {
        proxy_pass http://127.0.0.1:3356;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Upgrade-Handling (für SSE harmlos, für WebSocket bereit)
        proxy_set_header Connection        "";
        proxy_set_header Upgrade           $http_upgrade;

        proxy_buffering    off;   # jedes Event sofort durchreichen
        proxy_cache        off;
        chunked_transfer_encoding off;
        proxy_read_timeout 3600s; # Stream bis zu einer Stunde idle offen halten
        proxy_send_timeout 3600s;
    }
}

Den Stream nicht puffern

Der häufigste SSE-Fehler ist ein Proxy, der die Antwort puffert. Mit proxy_buffering off und einem langen proxy_read_timeout in der /stream-Location kommen Anhang-Updates in Echtzeit an. Mit der Standardpufferung „hängen“ Events, bis die Verbindung schließt.

Caddy (automatisches HTTPS)

Caddy macht am wenigsten Arbeit. Es holt und erneuert die Let's-Encrypt-Zertifikate selbst, ohne certbot und Timer. Das ist die komplette Caddyfile:

track.example.com {
    reverse_proxy 127.0.0.1:3456
}

api.track.example.com {
    # SSE-/Streaming-Endpunkte: ohne Pufferung durchreichen
    @stream path_regexp stream ^/api/v1/.*/stream$
    reverse_proxy @stream 127.0.0.1:3356 {
        flush_interval -1
    }

    reverse_proxy 127.0.0.1:3356
}

Caddy macht das Richtige von allein

Caddy setzt X-Forwarded-For, X-Forwarded-Proto und X-Forwarded-Host automatisch. flush_interval -1 schaltet die Pufferung ab, damit SSE sofort fließt. WebSocket-Upgrades gehen ohne Zusatzkonfiguration durch. Achte nur darauf, dass HINATA_TRUSTED_PROXIES die Adresse abdeckt, von der Caddy den Container erreicht.

Für ein echtes Deployment auf Port 80/443 braucht Caddy eine gültige E-Mail für ACME. Beide DNS-Einträge müssen auf den Host zeigen:

{
    email admin@example.com
}

Traefik (Labels)

Läuft Traefik bei dir schon als Docker-Ingress, setzt du Labels an die Services hinata-app und hinata-server. Eine eigene Konfigurationsdatei brauchst du nicht. Das Beispiel nimmt einen websecure-Entrypoint auf :443 und einen Resolver namens le an:

services:
  hinata-server:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.hinata-api.rule=Host(`api.track.example.com`)"
      - "traefik.http.routers.hinata-api.entrypoints=websecure"
      - "traefik.http.routers.hinata-api.tls.certresolver=le"
      - "traefik.http.services.hinata-api.loadbalancer.server.port=8080"

  hinata-app:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.hinata-web.rule=Host(`track.example.com`)"
      - "traefik.http.routers.hinata-web.entrypoints=websecure"
      - "traefik.http.routers.hinata-web.tls.certresolver=le"
      - "traefik.http.services.hinata-web.loadbalancer.server.port=80"

Traefik und SSE

Traefik puffert Antworten standardmäßig nicht. Der SSE-Endpunkt für Anhänge funktioniert also sofort. Setze HINATA_TRUSTED_PROXIES auf das CIDR von Traefiks Container oder Netzwerk. Traefik reicht X-Forwarded-For weiter, und Hinata beachtet es nur von einem vertrauten Gegenpart.

Kalender-Abos nicht ins Access-Log schreiben

Mit der Schichtplanung kann jede Person ihre Schichten als Kalender abonnieren. Die Abo-Adresse sieht so aus:

https://api.track.example.com/api/v1/shifts/feed/<geheimer-teil>.ics

Der geheime Teil ist der einzige Schlüssel: Kalender-Apps melden sich nicht an. Wer die Adresse aus einem Log abschreibt, liest die Schichten dieser Person mit. Hinata selbst speichert nur einen Hash, und das Log des Servers ersetzt den geheimen Teil durch ***, auch wenn du zur Fehlersuche mehr protokollieren lässt (etwa mit HINATA_LOG_SECURITY=DEBUG). Dein Proxy protokolliert die Adresse aber im Access-Log, wenn du nichts dagegen tust. Ersetze den Pfad deshalb vor dem Schreiben.

nginx: im http-Block ein eigenes Logformat, das den Pfad maskiert, und dieses im API-Server-Block verwenden:

map $request_uri $hinata_logged_uri {
    ~^/api/v1/shifts/feed/  /api/v1/shifts/feed/***.ics;
    default                 $request_uri;
}

log_format hinata '$remote_addr - $remote_user [$time_local] '
                  '"$request_method $hinata_logged_uri $server_protocol" '
                  '$status $body_bytes_sent "$http_referer" "$http_user_agent"';

server {
    server_name api.track.example.com;
    access_log /var/log/nginx/access.log hinata;
    # … wie oben
}

Caddy: Caddy schreibt ohne log-Direktive kein Access-Log. Hast du eins aktiviert, filtere die URI:

api.track.example.com {
    log {
        format filter {
            wrap json
            request>uri regexp "^/api/v1/shifts/feed/[^/?]+" "/api/v1/shifts/feed/***"
        }
    }
    # … wie oben
}

Traefik: Das Access-Log ist standardmäßig aus. Brauchst du es, lass mit --accesslog.fields.names.RequestPath=drop den Pfad weg; Traefik kann einzelne Pfade nicht maskieren.

Was das Abo sonst noch braucht

Nichts. Der Feed läuft über dieselbe API-Subdomain und dieselbe Location wie alles andere. Er antwortet mit Cache-Control: private, damit kein gemeinsamer Cache ihn aufhebt, und ein Feed lässt sich höchstens einmal pro Minute abrufen.

Überprüfen, ob es funktioniert

# API über den Proxy erreichbar und gesund
curl -s https://api.track.example.com/actuator/health
# → {"status":"UP"}

# Öffentliche Metadaten (kein Token nötig)
curl -s https://api.track.example.com/api/v1/meta

# Web-App liefert HTML
curl -sI https://track.example.com | head -n 1

Prüf auch, ob echte Client-IPs geloggt werden. Ruf dazu von einem anderen Rechner einen Endpunkt auf und schau in die Serverlogs. Dort sollte deine IP stehen, nicht das Docker-Gateway. Steht dort die Adresse des Proxy, ist HINATA_TRUSTED_PROXIES falsch.

Nächste Schritte