From 0ae7069cc72a170440c4bccebed57fd1d2dcdfe6 Mon Sep 17 00:00:00 2001 From: KingKDot Date: Sat, 18 Jul 2026 20:22:16 -0500 Subject: [PATCH] give the option for doing local host http and then using a rev proxy --- .env.example | 12 ++++++++ Overlord-Server/.env.example | 13 +++++---- README.md | 37 +++++++++++++++++++------ deploy/reverse-proxy/Caddyfile.example | 9 ++++++ deploy/reverse-proxy/nginx.conf.example | 31 +++++++++++++++++++++ docker-compose.windows.yml | 2 +- 6 files changed, 90 insertions(+), 14 deletions(-) create mode 100644 deploy/reverse-proxy/Caddyfile.example create mode 100644 deploy/reverse-proxy/nginx.conf.example diff --git a/.env.example b/.env.example index 66d3d94..269c05d 100644 --- a/.env.example +++ b/.env.example @@ -29,6 +29,18 @@ # ============================================ # Default is 5173 # PORT=8080 +# Bind address inside the server. For Linux host-network reverse-proxy deployments, +# use 127.0.0.1. Docker Desktop containers must keep this at 0.0.0.0. +# HOST=0.0.0.0 + +# Bind the Docker Desktop published port to this host address. +# Set 127.0.0.1 when nginx/Caddy runs on the host. +# OVERLORD_PUBLISH_HOST=127.0.0.1 + +# Serve HTTP internally and require a trusted reverse proxy to terminate public TLS. +# The public browser/agent URL must remain HTTPS/WSS. +# OVERLORD_TLS_OFFLOAD=true +# OVERLORD_HEALTHCHECK_URL=http://127.0.0.1:5173/health # ============================================ # ADVANCED: Custom JWT secret diff --git a/Overlord-Server/.env.example b/Overlord-Server/.env.example index d849dab..2c66825 100644 --- a/Overlord-Server/.env.example +++ b/Overlord-Server/.env.example @@ -17,14 +17,17 @@ OVERLORD_PASS=admin JWT_SECRET= OVERLORD_AGENT_TOKEN= -# TLS/HTTPS Configuration (Always Enabled) -# Certificates are auto-generated if not present -# You can specify custom certificate paths: +# TLS/HTTPS Configuration +# By default, certificates are generated when missing and Overlord serves HTTPS. # OVERLORD_TLS_CERT=./certs/server.crt # OVERLORD_TLS_KEY=./certs/server.key - -# Optional: CA certificate for client certificate verification (mutual TLS) # OVERLORD_TLS_CA=./certs/ca.crt +# Reverse-proxy TLS offload. This serves internal HTTP only; keep the listener +# on loopback and expose HTTPS/WSS through nginx, Caddy, or another trusted proxy. +# HOST=127.0.0.1 +# OVERLORD_TLS_OFFLOAD=true +# OVERLORD_HEALTHCHECK_URL=http://127.0.0.1:5173/health + # Performance tuning PRUNE_BATCH=500 diff --git a/README.md b/README.md index ebe2e08..42cffd1 100644 --- a/README.md +++ b/README.md @@ -569,20 +569,41 @@ Override with: ### Reverse proxy TLS offload -If your platform terminates TLS before traffic reaches Overlord (Render, Caddy, nginx, etc.), set: +Overlord can serve HTTP only on loopback while nginx, Caddy, Traefik, IIS, or +another trusted reverse proxy owns the public HTTPS certificate. Browsers and +agents must still use the public `https://` / `wss://` address. -``` +For a native install or Linux Docker with host networking, add this to `.env`: + +```env +HOST=127.0.0.1 OVERLORD_TLS_OFFLOAD=true -OVERLORD_HEALTHCHECK_URL=http://localhost:5173/health -OVERLORD_PUBLISH_HOST=127.0.0.1 +OVERLORD_HEALTHCHECK_URL=http://127.0.0.1:5173/health ``` +For Docker Desktop (`docker-compose.windows.yml`), the container must listen on +all of its own interfaces while Docker publishes the port on host loopback: + +```env +HOST=0.0.0.0 +OVERLORD_PUBLISH_HOST=127.0.0.1 +OVERLORD_TLS_OFFLOAD=true +OVERLORD_HEALTHCHECK_URL=http://127.0.0.1:5173/health +``` + +Restart Overlord after changing `.env`. The reverse proxy upstream is then +`http://127.0.0.1:5173`. It must preserve `Host`, set +`X-Forwarded-Proto: https` and `X-Forwarded-For`, support WebSocket upgrades, +and use timeouts/body limits suitable for long sessions and file uploads. + +Ready-to-copy Caddy and nginx configurations are in `deploy/reverse-proxy/`. + When enabled: -- Container serves internal HTTP on `0.0.0.0:$PORT` -- External URL stays `https://...` through your platform proxy -- Health checks should use `http://localhost:$PORT/health` inside the container -- Don't expose the internal container HTTP port directly to the internet +- Overlord skips certificate generation and serves internal HTTP. +- Authentication cookies remain `Secure` because public TLS terminates at the proxy. +- Proxy source-IP headers are trusted for auditing, bans, and rate limiting. +- The internal HTTP listener must never be exposed directly to the internet. ### Source IP behind a domain / reverse proxy diff --git a/deploy/reverse-proxy/Caddyfile.example b/deploy/reverse-proxy/Caddyfile.example new file mode 100644 index 0000000..7806b9b --- /dev/null +++ b/deploy/reverse-proxy/Caddyfile.example @@ -0,0 +1,9 @@ +# Replace overlord.example.com with the public DNS name. Caddy obtains and +# renews the public certificate automatically. +overlord.example.com { + reverse_proxy 127.0.0.1:5173 { + header_up Host {host} + header_up X-Forwarded-Proto https + header_up X-Real-IP {remote_host} + } +} diff --git a/deploy/reverse-proxy/nginx.conf.example b/deploy/reverse-proxy/nginx.conf.example new file mode 100644 index 0000000..492de31 --- /dev/null +++ b/deploy/reverse-proxy/nginx.conf.example @@ -0,0 +1,31 @@ +# Place the map in nginx's http {} context. +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} + +server { + listen 443 ssl; + listen [::]:443 ssl; + server_name overlord.example.com; + + ssl_certificate /etc/letsencrypt/live/overlord.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/overlord.example.com/privkey.pem; + + # Keep this at least as large as the uploads allowed by Overlord. + client_max_body_size 2g; + + location / { + proxy_pass http://127.0.0.1:5173; + 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 X-Real-IP $remote_addr; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_read_timeout 300s; + proxy_send_timeout 300s; + proxy_buffering off; + } +} diff --git a/docker-compose.windows.yml b/docker-compose.windows.yml index 546e8d8..834201a 100644 --- a/docker-compose.windows.yml +++ b/docker-compose.windows.yml @@ -10,7 +10,7 @@ services: - type=local,dest=.docker-cache/buildx,mode=max container_name: overlord-server ports: - - "${PORT:-5173}:5173" + - "${OVERLORD_PUBLISH_HOST:-0.0.0.0}:${PORT:-5173}:5173" environment: PORT: 5173 HOST: 0.0.0.0