Skip to content

Reverse Proxy and HTTPS

Use HTTPS before exposing BillTracker beyond a trusted local network. A reverse proxy such as Caddy, nginx, or Traefik can terminate TLS and forward requests to the app. This page gives you the environment block to copy, the forwarded-protocol header to set, and the HSTS / CORS defaults to be aware of.

What environment should I set for a production HTTPS deployment?

HTTPS=true
COOKIE_SECURE=true
CSRF_HTTP_ONLY=true
CSRF_SAME_SITE=strict
CSRF_SECURE=true

For plain HTTP development only:

HTTPS=false
COOKIE_SECURE=false
CSRF_SECURE=false

Verify cookie flags behind your proxy

CSRF_HTTP_ONLY=true is the v0.35 default and is correct for the bundled SPA. The CSRF cookie's Secure decision uses Express req.secure — see Known Limitations for the proxy-hop edge case.

How do I tell the app the request was HTTPS?

Forward:

X-Forwarded-Proto: https

The session-cookie logic recognizes that header. In the current build, the CSRF cookie's Secure decision uses Express req.secure, so verify the emitted Set-Cookie flags in your proxy deployment.

Should I set CORS_ORIGIN?

Leave CORS_ORIGIN unset when Express serves both the API and frontend. Set it only for an intentional split-origin deployment:

CORS_ORIGIN=https://bills-ui.example.com

For the default same-origin deployment (recommended), the variable is not needed.

When does HSTS enable?

HTTPS=true enables:

Strict-Transport-Security: max-age=31536000; includeSubDomains

Do not enable HSTS for a plain HTTP deployment. HSTS sticks for the max-age even if you later turn off HTTPS, so make sure HTTPS is correctly terminated before enabling it.

See also

Next steps