Use your own reverse proxy

If you already run a reverse proxy, such as Nginx, Traefik, HAProxy, Nginx Proxy Manager or Cloudflare Tunnel, use it instead of Caddy. Start from the Docker Compose example and make three changes:

• Make Lunar Paper reachable only through the proxy. For a proxy running on the host, keep HTTP_BIND_ADDRESS=127.0.0.1 in .env. If it runs on another machine, choose the server interface in HTTP_BIND_ADDRESS and restrict the chosen HOST_PORT to the proxy in the firewall. A containerized proxy must share a suitable Docker network with Lunar Paper and reach its container port 3000.
• Tell Lunar Paper how many proxies there are. Set TRUST_PROXY_HOPS in compose.yaml to the number of proxies in front of Lunar Paper. This is usually "1". Never set it to trust an unlimited number.
• Set APP_URL to the public https:// address.

Keep the official PostgreSQL service and persistent volumes from the Compose guide. After startup, open the public APP_URL, unlock setup with SETUP_KEY and explicitly initialize a fresh installation or complete a required upgrade. The proxy does not change the database setup process.

What the existing reverse proxy must do

• Forward the original Host header.
• Send X-Forwarded-Proto: https and X-Forwarded-For.
• Pass WebSocket connections through, including the Upgrade and Connection headers.
• Turn off response buffering, so that streamed responses arrive as they are sent.
• Allow large request bodies for uploads. Lunar Paper applies its own size limits.

Nginx example

This example leaves out the certificate settings. Add the lines for your own certificate.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name paper.example.com;
    # ssl_certificate and ssl_certificate_key go here.

    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_buffering off;
    }
}