handbook.nginx.conf

server {
    listen 8080 default_server;
    server_name _;

    # Emit relative Location headers so redirects work behind the
    # Cloudflare Tunnel — otherwise nginx prepends the internal
    # listen address (http://localhost:8080/...) and the browser
    # follows the link to a host it can't reach.
    absolute_redirect off;

    root /usr/share/nginx/html;
    # nginx joins `index` against the request path, so `index de/index.html`
    # makes /de/ look up /de/de/index.html (→ 403). Use plain index.html and
    # let the explicit /-redirect below route to /de/.
    index index.html;

    # Hide nginx version in Server header.
    server_tokens off;

    # Casual access gate — keeps the handbook out of public crawlers and
    # casual visitors. Credentials are intentionally low-friction and
    # baked into the image; rotate by regenerating handbook.htpasswd
    # (htpasswd -nbBC 10 <user> <pass>) and rebuilding. /healthz bypasses
    # auth so the Dockerfile HEALTHCHECK and CI smoke test stay simple
    # without leaking the password into workflows.
    auth_basic "RealUnit Handbook";
    auth_basic_user_file /etc/nginx/handbook.htpasswd;

    # Security headers for a static, embed-safe handbook.
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    # Behind a Basic-Auth gate: never let Cloudflare or any shared cache
    # store responses. With the previous `public, max-age=300` setting,
    # Cloudflare extended the TTL to 4h and served cached 401s back to
    # properly authenticated clients (handbook re-prompt incident
    # 2026-05-23), and symmetrically cached authenticated 200s where
    # any unauth client could pull them. `Vary: Authorization` doesn't
    # save us — Cloudflare ignores Vary on non-Enterprise plans. The
    # only safe answer for gated content on this plan is no-store. The
    # handbook ships ~6 MB total (HTML + 26 PNG screenshots, ~225 KB
    # each); a hard-refresh re-pulls all of it from origin, but dfxprd
    # and dfxdev shrug at that, and the gate by design keeps the
    # audience tiny.
    add_header Cache-Control "private, no-store" always;

    # Gzip text assets — screenshots are PNG and skip compression.
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    # text/html is gzipped by default; do not list it again.
    gzip_types
        text/plain
        text/css
        text/javascript
        application/javascript
        application/json
        image/svg+xml;

    # Unauthenticated health endpoint — used by the Dockerfile HEALTHCHECK
    # and the handbook CI smoke test. Returns 200 without disclosing
    # handbook content. nginx's add_header inheritance is all-or-nothing
    # per location, so the server-level security headers are restated
    # here; otherwise defining add_header inside the block would silently
    # drop them. Cache-Control is "no-store" so a healthcheck answer is
    # never cached by intermediaries while the container is actually down.
    location = /healthz {
        auth_basic off;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
        add_header Cache-Control "no-store" always;
        default_type text/plain;
        return 200 "OK\n";
    }

    location = / {
        return 302 /de/;
    }

    # Legal downloads (/legal/*.pdf, /legal/*.docx) — the derived PDF/DOCX export
    # of assets/legal/*.md. Force a download disposition (nginx's default
    # mime.types has no .docx mapping; it would otherwise serve as
    # application/octet-stream, which downloads but without an explicit
    # filename). add_header is all-or-nothing per location, so the server-level
    # security headers are restated here. auth_basic is inherited — these stay
    # behind the same Basic-Auth gate as the rest of the handbook.
    location ~* \.(pdf|docx)$ {
        add_header Content-Disposition "attachment" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
        add_header Cache-Control "private, no-store" always;
        try_files $uri =404;
    }

    location / {
        try_files $uri $uri/ =404;
    }
}