From 362ace960dcbdd2c8258aa8258189a9521280d31 Mon Sep 17 00:00:00 2001
From: Pulse Monitor <pulse@pulse-monitor.dev>
Date: Tue, 19 Aug 2025 08:50:36 +0000
Subject: [PATCH] docs: clarify environment variable precedence behavior

- Add clear warnings that env vars override UI/system.json settings
- Update log messages to indicate when env vars are overriding values
- Document standard container practice: env vars have highest precedence
- Users must remove env vars to allow UI configuration to take effect

This prevents confusion when UI changes don't work due to env var overrides.
---
 README.md                 |  2 ++
 docs/DOCKER.md            |  2 ++
 internal/config/config.go | 11 ++++++-----
 3 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c3cd30f48..3bc155837 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,8 @@ services:
     volumes:
       - pulse_data:/data
     environment:
+      # NOTE: Env vars override UI settings. Remove env var to allow UI configuration.
+      
       # Network discovery
       # - DISCOVERY_SUBNET=192.168.1.0/24   # Your local subnet (default: auto-detect)
       
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 597935358..a7dcfa111 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -206,6 +206,8 @@ Common problems:
 
 ## Environment Variables Reference
 
+> **⚠️ Important**: Environment variables always override UI/system.json settings. If you set a value via env var (e.g., `DISCOVERY_SUBNET`), changes made in the UI for that setting will NOT take effect until you remove the env var. This follows standard container practices where env vars have highest precedence.
+
 ### Authentication
 | Variable | Description | Example |
 |----------|-------------|---------|
diff --git a/internal/config/config.go b/internal/config/config.go
index 6beda0c48..e14d65e58 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -386,26 +386,27 @@ func Load() (*Config, error) {
 		}
 	}
 	// Support env vars for important settings (override system.json)
+	// NOTE: Environment variables always take precedence over UI/system.json settings
 	if discoverySubnet := os.Getenv("DISCOVERY_SUBNET"); discoverySubnet != "" {
 		cfg.DiscoverySubnet = discoverySubnet
-		log.Info().Str("subnet", discoverySubnet).Msg("Discovery subnet set from DISCOVERY_SUBNET env var")
+		log.Info().Str("subnet", discoverySubnet).Msg("Discovery subnet overridden by DISCOVERY_SUBNET env var")
 	}
 	if logLevel := os.Getenv("LOG_LEVEL"); logLevel != "" {
 		cfg.LogLevel = logLevel
-		log.Info().Str("level", logLevel).Msg("Log level set from LOG_LEVEL env var")
+		log.Info().Str("level", logLevel).Msg("Log level overridden by LOG_LEVEL env var")
 	}
 	if connectionTimeout := os.Getenv("CONNECTION_TIMEOUT"); connectionTimeout != "" {
 		if d, err := time.ParseDuration(connectionTimeout + "s"); err == nil {
 			cfg.ConnectionTimeout = d
-			log.Info().Dur("timeout", d).Msg("Connection timeout set from CONNECTION_TIMEOUT env var")
+			log.Info().Dur("timeout", d).Msg("Connection timeout overridden by CONNECTION_TIMEOUT env var")
 		} else if d, err := time.ParseDuration(connectionTimeout); err == nil {
 			cfg.ConnectionTimeout = d
-			log.Info().Dur("timeout", d).Msg("Connection timeout set from CONNECTION_TIMEOUT env var")
+			log.Info().Dur("timeout", d).Msg("Connection timeout overridden by CONNECTION_TIMEOUT env var")
 		}
 	}
 	if allowedOrigins := os.Getenv("ALLOWED_ORIGINS"); allowedOrigins != "" {
 		cfg.AllowedOrigins = allowedOrigins
-		log.Info().Str("origins", allowedOrigins).Msg("Allowed origins set from ALLOWED_ORIGINS env var")
+		log.Info().Str("origins", allowedOrigins).Msg("Allowed origins overridden by ALLOWED_ORIGINS env var")
 	}
 	
 	// Set log level