From 6bab6df819c769233f1fbcc68af2d7c15e8617b5 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 19 Jun 2026 12:04:52 +0530
Subject: [PATCH] chore: update .env.example for runtime configuration

---
 surfsense_web/.env.example | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/surfsense_web/.env.example b/surfsense_web/.env.example
index 11646c948..7d03cf498 100644
--- a/surfsense_web/.env.example
+++ b/surfsense_web/.env.example
@@ -14,7 +14,10 @@ SURFSENSE_BACKEND_INTERNAL_URL=http://backend:8000
 # ─────────────────────────────────────────────────────────────────────────────
 # Runtime configuration (read at runtime by the server, no rebuild needed)
 # ─────────────────────────────────────────────────────────────────────────────
-
+# Configure these plain variables for runtime behavior. They are read by server
+# code when the app starts/serves requests, so changing them requires restarting
+# the web process but not rebuilding the frontend bundle.
+#
 # Authentication method: LOCAL (email/password) or GOOGLE (OAuth).
 AUTH_TYPE=LOCAL
 # Document parsing backend: DOCLING, LLAMACLOUD, etc.
@@ -22,16 +25,6 @@ ETL_SERVICE=DOCLING
 # Deployment mode: self-hosted or cloud.
 DEPLOYMENT_MODE=self-hosted
 
-# ─────────────────────────────────────────────────────────────────────────────
-# Build-time fallbacks for packaged clients (e.g. Electron) without a runtime
-# config provider. Optional; Docker reads the plain runtime vars above first.
-# ─────────────────────────────────────────────────────────────────────────────
-# NEXT_PUBLIC_AUTH_TYPE=GOOGLE
-# NEXT_PUBLIC_ETL_SERVICE=DOCLING
-# NEXT_PUBLIC_DEPLOYMENT_MODE=self-hosted
-# Overrides the app version shown in the UI (defaults to package.json version).
-# NEXT_PUBLIC_APP_VERSION=
-
 # ─────────────────────────────────────────────────────────────────────────────
 # Database (Contact Form, optional)
 # ─────────────────────────────────────────────────────────────────────────────
@@ -72,3 +65,20 @@ NEXT_PUBLIC_GOOGLE_ADSENSE_SLOT_FREE_HUB_BEFORE_FAQ=
 # ─────────────────────────────────────────────────────────────────────────────
 NEXT_PUBLIC_GLOBAL_ANNOUNCEMENT_ENABLED=false
 NEXT_PUBLIC_GLOBAL_ANNOUNCEMENT_MESSAGE=
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Internal build-time fallbacks
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Most deployments should leave these unset.
+#
+# These are only for SurfSense-managed production/cloud builds or packaged
+# clients that do not have the normal server runtime config available.
+#
+# NEXT_PUBLIC_* values are embedded into the browser bundle during `next build`.
+# Changing them after the bundle is built has no effect.
+
+# NEXT_PUBLIC_AUTH_TYPE=GOOGLE
+# NEXT_PUBLIC_ETL_SERVICE=DOCLING
+# NEXT_PUBLIC_DEPLOYMENT_MODE=self-hosted
+# NEXT_PUBLIC_APP_VERSION=
\ No newline at end of file