diff --git a/deploy/.env.example b/deploy/.env.example
index 60ec51ec..13803325 100644
--- a/deploy/.env.example
+++ b/deploy/.env.example
@@ -54,7 +54,10 @@ ADMIN_PASSWORD=
 # -----------------------------------------------------------------------------
 # JWT Configuration
 # -----------------------------------------------------------------------------
-# Leave empty to auto-generate (recommended)
+# IMPORTANT: Set a fixed JWT_SECRET to prevent login sessions from being
+# invalidated after container restarts. If left empty, a random secret will
+# be generated on each startup, causing all users to be logged out.
+# Generate a secure secret: openssl rand -hex 32
 JWT_SECRET=
 JWT_EXPIRE_HOUR=24
 
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index ca9ea031..6c344614 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -72,7 +72,10 @@ services:
       # =======================================================================
       # JWT Configuration
       # =======================================================================
-      # Leave empty to auto-generate (recommended)
+      # IMPORTANT: Set a fixed JWT_SECRET to prevent login sessions from being
+      # invalidated after container restarts. If left empty, a random secret
+      # will be generated on each startup.
+      # Generate a secure secret: openssl rand -hex 32
       - JWT_SECRET=${JWT_SECRET:-}
       - JWT_EXPIRE_HOUR=${JWT_EXPIRE_HOUR:-24}