diff --git a/docker/.env.example b/docker/.env.example
index 201b60e8c..58549acba 100644
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -15,6 +15,30 @@ SURFSENSE_VERSION=latest
 # REQUIRED: Generate a secret key with: openssl rand -base64 32
 SECRET_KEY=replace_me_with_a_random_string
 
+
+# ------------------------------------------------------------------------------
+# Ports (change to avoid conflicts with other services on your machine)
+# ------------------------------------------------------------------------------
+
+# BACKEND_PORT=8000
+# FRONTEND_PORT=3000
+# ELECTRIC_PORT=5133
+# FLOWER_PORT=5555
+
+# ------------------------------------------------------------------------------
+# Custom Domain / Reverse Proxy
+# ------------------------------------------------------------------------------
+# ONLY set these if you are serving SurfSense on a real domain via a reverse
+# proxy (e.g. Caddy, Nginx, Cloudflare Tunnel).
+# For standard localhost deployments, leave all of these commented out —
+# they are automatically derived from the port settings above.
+#
+# NEXT_FRONTEND_URL=https://app.yourdomain.com
+# BACKEND_URL=https://api.yourdomain.com
+# NEXT_PUBLIC_FASTAPI_BACKEND_URL=https://api.yourdomain.com
+# NEXT_PUBLIC_ELECTRIC_URL=https://electric.yourdomain.com
+
+
 # Auth type: LOCAL (email/password) or GOOGLE (OAuth)
 AUTH_TYPE=LOCAL
 
@@ -30,31 +54,6 @@ ETL_SERVICE=DOCLING
 # Cohere: cohere://embed-english-light-v3.0 (set COHERE_API_KEY below)
 EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 
-# ------------------------------------------------------------------------------
-# Ports (change these to avoid host conflicts — everything auto-derives)
-# ------------------------------------------------------------------------------
-
-# BACKEND_PORT=8000
-# FRONTEND_PORT=3000
-# ELECTRIC_PORT=5133
-# FLOWER_PORT=5555
-
-# Frontend URL used by backend for CORS and OAuth redirects.
-# Auto-derived from FRONTEND_PORT for localhost. (Set explicitly for reverse proxy)
-# NEXT_FRONTEND_URL=http://localhost:3000
-
-# Backend URL for OAuth callback redirects (set when behind a reverse proxy)
-# BACKEND_URL=https://api.yourdomain.com
-
-# ------------------------------------------------------------------------------
-# Frontend URL Overrides (reverse proxy / custom domains)
-# ------------------------------------------------------------------------------
-# These are auto-derived from the port settings above for localhost deployments.
-# You only need to set these explicitly when using a reverse proxy with real
-# domains (e.g. Caddy, Nginx, Cloudflare Tunnel).
-#
-# NEXT_PUBLIC_FASTAPI_BACKEND_URL=https://api.yourdomain.com
-# NEXT_PUBLIC_ELECTRIC_URL=https://electric.yourdomain.com
 
 # ------------------------------------------------------------------------------
 # Database (defaults work out of the box, change for security)