give the option for doing local host http and then using a rev proxy

.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

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

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
 

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}
+	}
+}

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;
+    }
+}

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