Setting up a Reverse Proxy

When exposing Liwan to the public internet, a reverse proxy is a convenient way to handle HTTPS and keep Liwan itself on a private or local address. This guide uses Caddy.

Other common choices include Nginx, Traefik, and HAProxy.

Setting up Caddy

Firewall Configuration

Depending on your setup, you might want to configure your firewall to only allow incoming traffic on ports 80 and 443 from the internet, as Liwan listens on all interfaces by default. A simple way to do this on many Linux distributions is using ufw, check the official documentation for more information.

1. Install Caddy
   First, install Caddy on your server. You can download the latest version from the official website. Depending on how you install Caddy, you may need to set up a service to run it in the background.

2. Configure Caddy
   A basic Caddy configuration file might look like this:

   /etc/caddy/Caddyfile

   liwan.example.com {
       reverse_proxy localhost:9042
       tls you@example.com
   }

   This tells Caddy to serve liwan.example.com, proxy requests to Liwan on port 9042, and use Let’s Encrypt for certificates.

3. Start Caddy
   Again, depending on your setup, you may need to start Caddy manually or set it up as a service. See the Keep Caddy Running section of the Caddy documentation for more information.

   Once Caddy is running, you should be able to access Liwan by visiting https://liwan.example.com.

Client IP Headers

Liwan uses the request IP for visitor identification and optional GeoIP lookups. When Liwan is behind a reverse proxy, the proxy should forward the original client IP.

Liwan checks these headers (in this order) before falling back to the socket source IP:

• cf-connecting-ip
• fly-client-ip
• true-client-ip
• x-real-ip
• cloudfront-viewer-address
• x-forwarded-for
• forwarded

For multi-hop header formats (x-forwarded-for and forwarded), Liwan currently uses the last entry in the list.

Forwarded IP headers can be spoofed if Liwan receives them directly from the public internet. Only trust forwarding headers from infrastructure you control, such as your reverse proxy.

If possible, configure that proxy to strip incoming client-provided forwarding headers and set its own canonical values.

For Caddy, the default reverse_proxy setup already forwards X-Forwarded-For and related headers.