HealthLog/docs/self-hosting/reverse-proxy.md

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.

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 <network> 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 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:

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:

   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 <VersionPoller> 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:

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.

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.