Setting up a Reverse Proxy

A reverse proxy can provide HTTPS and route public traffic to liwan while liwan listens on a local address. This guide uses Caddy. Other options include Nginx, Traefik, and HAProxy.

Setting up Caddy

Firewall configuration

Allow public access to ports 80 and 443, and restrict direct access to liwan on port 9042.

1. Install Caddy

   Install Caddy using a supported package or the official download. Configure it to run as a service.

2. Configure Caddy

   Create a basic Caddy configuration:

   /etc/caddy/Caddyfile

   liwan.example.com {
       reverse_proxy localhost:9042
   }

   Caddy routes requests to liwan on port 9042 and automatically manages the TLS certificate.

3. Start Caddy

   Start or restart the Caddy service. You can then open https://liwan.example.com.

Client IP Headers

liwan uses the client IP for visitor grouping, optional GeoIP lookup, and rate limiting. In 1.7, it accepts X-Forwarded-For from IPv4 and IPv6 loopback proxies by default. The Caddy configuration above works with these defaults because Caddy connects from loopback.

Upgrading to 1.7

If your proxy connects from another host, container, or network, add the proxy’s address to trusted_proxies. Otherwise, an untrusted private proxy leaves events without a usable client IP. This affects visitor grouping, MaxMind lookup, page-exit tracking, and login and event rate limits.

For a proxy on a Docker network, use the network’s actual subnet. Docker’s default bridge network is commonly 172.17.0.0/16:

trusted_headers = ["X-Forwarded-For"]
trusted_proxies = ["172.17.0.0/16"]

Run docker network inspect <network> to check the subnet. Docker can select a different range, especially when other networks already exist or the daemon uses custom address pools.

You can set trusted_proxies = "*" when only trusted systems can connect to liwan, such as within an isolated container network. Do not use * when clients can reach liwan directly because they could spoof forwarding headers and bypass per-IP rate limits.

Provider presets select the appropriate client IP header:

Preset	Header
akamai	True-Client-IP
cloudflare	CF-Connecting-IP
cloudfront	CloudFront-Viewer-Address
fastly	Fastly-Client-IP
fly	Fly-Client-IP

For example:

trusted_headers = "cloudflare"
trusted_proxies = ["203.0.113.10", "2001:db8:1234::/48"]

Replace these documentation ranges with the actual proxy addresses you trust. For multi-hop X-Forwarded-For and Forwarded values, liwan walks from the nearest proxy toward the client and stops at the first untrusted address.

See the Configuration Reference for custom headers and all defaults.