# Reverse proxy configuration The bundled `docker-compose.yml` exposes HealthLog on plain HTTP at `localhost:3000`. Production deployments front the container with a reverse proxy that terminates TLS, sets the forwarded headers the rate-limiter trusts, and passes the Coach's Server-Sent Events stream through unbuffered with a generous read timeout. This guide gives copy-paste blocks for five common fronts. Pick one; the env-var pairing is identical across them. If the instance only needs to be reachable from your own devices, none of them is required: `tailscale serve` terminates trusted HTTPS on the tailnet with no extra container. See [`docs/self-hosting/tailscale.md`](tailscale.md). ## Pre-flight — env vars the proxy interacts with | Variable | Required for | Notes | | ------------------------ | ---------------------------------------------- | ---------------------------------------- | | `NEXT_PUBLIC_APP_URL` | Every public-facing absolute URL the UI emits | Must match the hostname the proxy serves | | `APP_URL` | Server-side absolute URLs from background jobs | Mirror of the above; both must match | | `TRUST_PROXY_HOPS` | `X-Forwarded-For` chain trust | Defaults to `1` — one trusted hop | | `TRUSTED_PROXY_CIDRS` | Which connections may report a client address | Unset: any private address; see below | | `TRUST_CF_CONNECTING_IP` | Reading the visitor address Cloudflare sends | Off unless `1`; see the warning below | Set the URL pair to the public origin (`https://your-instance.example.com`) and restart the `app` container. The image reads both at startup; no rebuild needed. All five variables are on the shipped `docker-compose.yml` `environment:` whitelist, so a value in `.env` reaches the container without editing the compose file. (Before v1.37.33 the whitelist was missing `TRUST_PROXY_HOPS`; on those versions add `TRUST_PROXY_HOPS: "${TRUST_PROXY_HOPS:-}"` to the `app` service's `environment:` block yourself.) ### `TRUST_PROXY_HOPS` — what to set it to `src/lib/api-response.ts` (`getClientIp`) reads the `X-Forwarded-For` chain from the **right**, counting back `TRUST_PROXY_HOPS` entries. This guards against a client rotating `X-Forwarded-For` per request to defeat IP-based rate limits. | Topology | `TRUST_PROXY_HOPS` | | --------------------------------------------------------- | ---------------------------------- | | App is internet-facing with no proxy | `0` (the connection's own address) | | Single proxy in front (Caddy / Traefik / Nginx / Coolify) | `1` (default) | | Cloudflare → your proxy → app | `2` | | Cloudflare → Coolify-Tunnel → Coolify → app | `3` | A misconfigured count logs a one-shot warning to stderr and collapses every anonymous caller into one shared rate-limit bucket. Match the value to the actual hop count. Forwarding headers are believed only from a connection whose own address is not a public one, which is where a proxy you run connects from: - IPv4: loopback (`127.0.0.0/8`), `0.0.0.0/8`, the private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), CGNAT (`100.64.0.0/10`, Tailscale), link-local (`169.254.0.0/16`), the reserved blocks `192.0.0.0/24` and `198.18.0.0/15`, and everything from `224.0.0.0` up (multicast and reserved); - IPv6: `::` and `::1`, link-local (`fe80::/10`), site-local (`fec0::/10`), unique-local (`fc00::/7`, Tailscale), multicast (`ff00::/8`), and an IPv4-mapped or embedded address from one of the IPv4 ranges above. The reserved and multicast blocks are in the list because no host on the internet can open a connection from them, so a peer there sits on a network you run. A request that reaches HealthLog straight from a public address carries headers its sender wrote, so HealthLog ignores them and uses the connection's own address, and says so once in the log. The log line also shows up when the published port is open to the internet beside the proxy; bind it to the proxy's network or to `127.0.0.1` then. That list is the default when `TRUSTED_PROXY_CIDRS` is unset, and it is only as good as the network in front of the port. Read the next section before relying on it. ### `TRUSTED_PROXY_CIDRS` — name the proxy Set `TRUSTED_PROXY_CIDRS` to the addresses your reverse proxy connects from, as comma-separated CIDRs (IPv4 or IPv6; a bare address counts as a single host). Once it is set, only a connection from inside those ranges may report the client's address. Every other connection is its own client, whatever its address, private ones included, and the log says so once. Why it matters: some setups make every caller look like a private address. Docker Desktop, OrbStack, and Docker's `docker-proxy` (the userland proxy behind a published port such as `3000:3000`) forward each connection from the gateway address of the Docker network, which is private. On those hosts, someone who can reach the published port directly, from the LAN or from the internet if the port is open, passes the private-address check and can again choose the address that every per-IP rate limit, the audit log and the sign-in notices see, a new one per request if they like. Naming your proxy closes that. The default port binding in `docker-compose.yml` stays as it is (LAN installs rely on it); this variable is the fix. What to set: | Where the proxy runs | `TRUSTED_PROXY_CIDRS` | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | On the same host, proxying to `127.0.0.1:3000` (bare Nginx, Caddy) | `127.0.0.1/32,::1/128` | | In a container on a Docker network with HealthLog (Traefik, NPM, Coolify) | that network's subnet, e.g. `172.18.0.0/16` (`docker network inspect ` shows it under `IPAM`) | | On another machine that connects from a public address | that machine's address, e.g. `198.51.100.7/32` | | No proxy, or `tailscale serve` only | leave it unset | At boot the app logs one `[proxy-trust]` line naming the rule in force: which connections it reads forwarding headers from and how many hops deep. A value that is not a CIDR is logged as an error, and until it is fixed no connection may report a client address. **A proxy that connects from a public address.** Without `TRUSTED_PROXY_CIDRS`, such a proxy is not believed: every request through it resolves to the proxy's own address, so all your users share one rate-limit bucket and one person mistyping a password can hold sign-in back for everyone. Releases before v1.46 believed any peer, so this shows up after the upgrade. Set `TRUSTED_PROXY_CIDRS` to the proxy's address (or put the proxy on a private network with HealthLog) and restart. ### `TRUST_CF_CONNECTING_IP` — only when the origin takes Cloudflare only With `TRUST_CF_CONNECTING_IP=1` HealthLog takes the visitor's address from the `CF-Connecting-IP` header, before any of the checks above: from every connection, whatever its address, and whatever `TRUST_PROXY_HOPS` says. Cloudflare sets that header on every request through its edge, but any client can send it too. So the flag is safe only when nothing but Cloudflare can reach the origin: a Cloudflare Tunnel with no published port, or a firewall that admits only [Cloudflare's address ranges](https://www.cloudflare.com/ips/) to the port HealthLog or its proxy listens on (Authenticated Origin Pulls on top is better still). If the origin also answers on its own public address, a caller who finds it chooses the address every per-IP rate limit, the audit log and the sign-in locations record, and changes it on every request. Without Cloudflare in front, leave the flag unset. `X-Real-IP` gets the same trust as `X-Forwarded-For`. It is read only when `TRUST_PROXY_HOPS` is exactly `1` and the request carries no `X-Forwarded-For`, which covers a single proxy that sets only `X-Real-IP`. With `0` neither header is believed, because without a proxy in front both come from the caller; the address the connection came from is used instead. With `2` or more, the hop count describes an `X-Forwarded-For` chain, so have your proxies send one. If requests arrive with a forwarding header the setting does not let HealthLog read, the log shows one warning naming the header and the setting. Every anonymous caller then shares one rate-limit bucket, so one person mistyping a password can hold sign-in back for everyone. The usual cause is `0` behind a proxy that sends only `X-Real-IP`: set `1`. ## Caddy `Caddyfile`: ``` your-instance.example.com { encode zstd gzip reverse_proxy localhost:3000 { header_up X-Forwarded-For {remote_host} header_up X-Forwarded-Proto {scheme} header_up Host {host} flush_interval -1 } } ``` `flush_interval -1` disables response buffering so the SSE events surface without batching delays. With Caddy as the only hop, leave `TRUST_PROXY_HOPS=1`. ## Traefik `docker-compose.override.yml` snippet: ```yaml services: app: labels: - "traefik.enable=true" - "traefik.http.routers.healthlog.rule=Host(`your-instance.example.com`)" - "traefik.http.routers.healthlog.entrypoints=websecure" - "traefik.http.routers.healthlog.tls.certresolver=letsencrypt" - "traefik.http.services.healthlog.loadbalancer.server.port=3000" - "traefik.http.middlewares.healthlog-headers.headers.customrequestheaders.X-Forwarded-Proto=https" - "traefik.http.routers.healthlog.middlewares=healthlog-headers" ``` Traefik forwards `X-Forwarded-For` by default and does not buffer responses, so the SSE stream passes through as-is. Pair with `TRUST_PROXY_HOPS=1`. If Traefik sits behind Cloudflare, set it to `2` so the rate-limiter reads the real client IP that Cloudflare placed in the chain. ## Nginx Proxy Manager In the NPM UI: 1. **Proxy Hosts → Add Proxy Host.** 2. **Domain Names:** `your-instance.example.com`. 3. **Scheme:** `http`; **Forward Hostname / IP:** the Docker host or internal hostname; **Forward Port:** `3000`. 4. **Websockets Support** may stay on or off; the Coach stream is SSE over plain HTTP, not WebSockets. What matters is the buffering and timeout config in step 6. 5. **SSL tab:** request a Let's Encrypt certificate, force SSL. 6. **Advanced tab — Custom Nginx Configuration:** ```nginx proxy_read_timeout 300s; ``` Nginx Proxy Manager configures the standard forwarded headers automatically and adds the WebSocket upgrade directives when Websockets Support is enabled. The 300-second read timeout matters for long-running insight generations — anything shorter will cut streamed responses mid-flight. Pair with `TRUST_PROXY_HOPS=1`. ## Coolify Coolify's bundled Traefik handles most of this. The pieces that need operator attention: 1. **Application → Domains:** set `https://your-instance.example.com`. Coolify provisions the certificate and adds the Traefik labels. 2. **Application → Environment Variables:** set `NEXT_PUBLIC_APP_URL`, `APP_URL`, and any optional secrets (`WITHINGS_*`, `APNS_*`, `LOKI_*`). 3. **Application → General → Pull policy:** `always`. The bundled `docker-compose.yml` declares this explicitly (v1.4.34.2 fix) so Coolify re-checks the GHCR digest on every redeploy instead of reusing the cached `:latest` layer. 4. **Notifications → Webhook:** point at `/api/internal/deploy-webhook` with the `X-Deploy-Webhook-Secret` header set to `DEPLOY_WEBHOOK_SECRET`. The app gates the endpoint with a timing-safe compare against that env var. ### DO NOT set as runtime env vars The following variables are **build-time only** — they are injected via `--build-arg` by the `docker-publish` workflow and baked into the shipped image. Setting them under Coolify's _Environment Variables_ panel has zero effect on the running container, and the stale value becomes a misleading artefact next time someone audits the deploy config: - `NEXT_PUBLIC_APP_VERSION` — sourced from the GHCR tag at build time. Next.js inlines the value into both the client bundle (so the `` self-healing reload compares against the shipped shell) and the `/api/version` server route (so the public endpoint returns the same string). The `env: {…}` block in `next.config.ts` short-circuits the runtime `process.env` read. - `NEXT_PUBLIC_APP_BUILD_SHA`, `NEXT_PUBLIC_APP_BUILT_AT` — same pattern. The CI workflow stamps the short SHA and build timestamp into the image during `pnpm build`. If you spot any of these in the Coolify panel, delete the entry. The image already carries the correct value. Coolify-Tunnel adds one hop to the chain; pair with `TRUST_PROXY_HOPS=2`. If you front Coolify itself with Cloudflare, bump to `3`. ## Bare Nginx `/etc/nginx/sites-available/healthlog`: ```nginx upstream healthlog { server 127.0.0.1:3000; keepalive 16; } server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name your-instance.example.com; ssl_certificate /etc/letsencrypt/live/your-instance.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-instance.example.com/privkey.pem; client_max_body_size 1600M; # Apple Health export.zip cap is 1.5 GB location / { proxy_pass http://healthlog; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; 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_read_timeout 300s; proxy_buffering off; } } server { listen 80; listen [::]:80; server_name your-instance.example.com; return 301 https://$host$request_uri; } ``` `client_max_body_size 1600M` is the load-bearing setting if you plan to support Apple Health `export.zip` uploads — the app caps the upload at 1.5 GB and Nginx will reject the body before the app sees it otherwise. `proxy_buffering off` keeps streamed insight events flowing without buffer pauses. Pair with `TRUST_PROXY_HOPS=1`. ## Verifying the proxy chain Once the proxy is in front, hit `https://your-instance.example.com/api/version` from outside the host and check `docker compose logs app` for the request. The wide-event log line should carry a non-null client IP that matches your real source address. A `null` IP or a single `unknown` rate-limit bucket means `TRUST_PROXY_HOPS` is set higher than the actual proxy hop count, or the proxy is dropping the `X-Forwarded-For` header entirely. The one-shot stderr warning `[getClientIp] TRUST_PROXY_HOPS=N but X-Forwarded-For carried M entries` confirms a mismatch. Adjust the env var down to the actual chain length and restart. If every request logs the same client address, the proxy's own, the proxy is not one HealthLog believes: the `[getClientIp]` warning about a connection "from a public address" or "from outside TRUSTED_PROXY_CIDRS" names the case. Add the proxy's address to `TRUSTED_PROXY_CIDRS`. A `TRUST_PROXY_HOPS` value that is not a whole number resolves no client address at all (requests keep working) and is named in the `[proxy-trust]` boot line. ## Running over plain HTTP on a LAN (no reverse proxy) The session cookie carries the `Secure` flag by default under `NODE_ENV=production`, which is what the bundled Docker image runs. On a plain-HTTP origin that is not `localhost` / `127.0.0.1` / `::1`, modern browsers silently drop a `Secure` cookie before sending the next request — the login round-trip looks like it succeeds (the server returns 200 + `Set-Cookie`) but the very next page load 401s and bounces back to `/auth/login`. If you genuinely want to serve HealthLog on `http://10.0.0.42:3000` or `http://healthlog.lan:3000` (NAS, homelab, Tailscale-only surface) and trust the network the traffic crosses, set: ``` SESSION_COOKIE_SECURE=false ``` in your `.env`. The session, onboarding-hint, Withings OAuth state, and Codex device-OAuth state cookies all stop emitting `Secure` and login works over HTTP. The trade-off is explicit: the session cookie crosses the wire unencrypted, so the network it traverses needs to be one you control. For the Tailscale case specifically there is a better option than lifting the flag: `tailscale serve` gives the same surface real HTTPS with a tailnet-trusted certificate, and `SESSION_COOKIE_SECURE` stays unset. See [`docs/self-hosting/tailscale.md`](tailscale.md). **Do not set this on a deployment that ever serves plain HTTP to the open internet.** Anyone with passive network access can capture the session cookie and impersonate the user. The right answer for any public-facing host is the reverse proxy + Let's Encrypt path documented above. The default behaviour is unchanged when this variable is unset — deployments behind an HTTPS-terminating proxy keep setting `Secure` exactly as before.