Behind a proxy or tunnel
Ottertrail uses each visitor’s IP address in memory for three things: rate limits, the daily visitor ID, and the location. A proxy hides that address, because every request seems to come from the proxy. So the API must know how many proxies are in front of it.
The default: Caddy, one hop
Section titled “The default: Caddy, one hop”In the Compose stack, Caddy is the only proxy:
- Caddy replaces any
X-Forwarded-Forheader that a client sends with the address it sees. - The Compose file sets
TRUST_PROXY=1, so the API trusts exactly one proxy hop.
The API therefore sees the real address, and a client cannot fake one. You do not need to set anything.
Another proxy, a CDN, or a tunnel in front
Section titled “Another proxy, a CDN, or a tunnel in front”Putting a CDN, a load balancer, or a tunnel in front of Caddy is not supported now. With one more hop, every request seems to come from that proxy:
- All visitors share one rate limit, one visitor ID, and one location.
- If the proxy runs in a cloud data center, the instance can ignore every browser event as a bot.
Caddy must then trust the outer proxy, and the API must trust one more hop. The Compose file does not set this up.
Run the stack with Caddy on ports 80 and 443 of its own server, as Install Ottertrail describes.
Running the image without Caddy
Section titled “Running the image without Caddy”If you run the image on a platform that gives it HTTPS, without the Compose file, set TRUST_PROXY yourself. This setup is not tested.
- Set it to the number of proxy hops in front of the API, from 1 to 10. Or set it to a comma-separated list of the proxies’ IP addresses or CIDR ranges.
- Without a proxy, leave it unset. Otherwise any client can claim any address.
- If you leave it unset behind a proxy, every visitor seems to come from the proxy’s address.
GEO_SOURCE=cloudflare takes locations from Cloudflare’s headers in place of the location database. Use it only when every request passes through Cloudflare, because any client can send these headers.
See the other variables in the configuration reference.