Behind a reverse proxy

The server listens on plain HTTP, on PITWALL_HTTP_ADDR (:8080 by default). To reach it over HTTPS, put a reverse proxy in front.

What the proxy must do

Requirement	Why
Forward Host unchanged	Every request that changes something is checked: its Origin must name the same host
Set X-Forwarded-For	The sign-in limiter counts failures per client address
Set X-Forwarded-Proto	The server marks the session cookie Secure, and writes https:// in the runner install command, only on a request it knows was HTTPS
Hold a request open for longer than 25 seconds	A runner waits for work on a request held open up to 25 seconds. A proxy that cuts it sooner breaks every runner

Trusting the proxy

The server believes X-Forwarded-For and X-Forwarded-Proto only on a connection from an address listed in PITWALL_TRUSTED_PROXIES: comma-separated addresses and CIDR ranges. From anyone else they are ignored.

# An example: the range of the Docker network the proxy reaches the server through
PITWALL_TRUSTED_PROXIES=172.18.0.0/16

List the address the server sees the proxy connect from. Behind Docker’s networking that may be a gateway of the Docker network, not the proxy’s own address. An entry that is neither an address nor a range stops the server at start.

A missing entry shows in two places: the session cookie has no Secure flag on your HTTPS address, and Register runner shows an install command starting with http://.

HTTPS only

For an instance only ever reached over HTTPS, set PITWALL_COOKIE_SECURE=true: the session cookie is then always Secure, whatever the proxy says. Signing in over plain HTTP stops working.

Set PITWALL_PUBLIC_URL to the address people reach Pitwall at, such as https://pitwall.example.com: notifications and password reset links are built from it. See Configuration.