env mode deferred

Author: bonsaibauer

README.md

@@ -260,13 +260,19 @@ Common adjustments:
 | `-e PUID/PGID` | In this tutorial: `-e PUID=$(id -u enshrouded) -e PGID=$(id -g enshrouded)`; you can also set them directly, e.g. `-e PUID=1001 -e PGID=1001`. |
 | `-e EN_PROFILE` | `-e EN_PROFILE=default` (selects Enshrouded profile template on first bootstrap for fresh/missing config). |
 | `-e MANAGER_PROFILE` | `-e MANAGER_PROFILE=default` (selects Server Manager profile template on first bootstrap for fresh/missing config). |
-| `-e ENSHROUDED_QUERY_PORT` | `-e ENSHROUDED_QUERY_PORT=15637` (must match the internal port in `-p ...:<internal>/udp`). |
+| `-e ENSHROUDED_QUERY_PORT` | `-e ENSHROUDED_QUERY_PORT=15637` (must match the internal port in `-p ...:<internal>/udp`; `env_mode=deferred`, so runtime can also resolve from config/profile fallback). |
 | `-e ENSHROUDED_NAME` | `-e ENSHROUDED_NAME="My Enshrouded Server"` (server name shown in the in-game server browser). |
 | `-v <host_path>:/home/enshrouded/server` | `-v /home/enshrouded/server_1:/home/enshrouded/server` |
 | `bonsaibauer/enshrouded_server_docker:<tag>` | `bonsaibauer/enshrouded_server_docker:dev_latest` (or `latest`; see [Docker Hub tags](https://hub.docker.com/r/bonsaibauer/enshrouded_server_docker/tags)). |
 
 </details>
 
+> [!NOTE]
+> `ENSHROUDED_QUERY_PORT` uses `env_mode=deferred`:
+> - startup validation does not hard-fail if it is initially empty,
+> - runtime init still requires a final resolved value (ENV or valid config/profile fallback),
+> - the menu treats this field as hard ENV-managed (locked in editors).
+
 <details>
 <summary><strong>Profiles Explained</strong></summary>
 

docs/README_DOCKER_HUB.md

@@ -41,6 +41,9 @@ docker run \
   bonsaibauer/enshrouded_server_docker:dev_latest
 ```
 
+> [!NOTE]
+> `ENSHROUDED_QUERY_PORT` is `env_mode=deferred`: early startup validation can proceed when empty, but runtime still needs a resolved value (ENV or valid config/profile fallback). In menu editors this field is treated as hard ENV-managed (locked).
+
 > [!TIP]
 > 🎛️ Open the control center with: `docker exec -it enshroudedserver menu`
 

docs/commands.md

@@ -260,6 +260,10 @@ docker exec enshroudedserver env-validation [verify|init-runtime|check <name> <v
 - `verify`: Full ENV validation.
 - `init-runtime`: Initializes runtime values/defaults.
 - `check <name> <value>`: Validates one variable.
+- ENV policy modes from spec:
+- `soft`: Optional ENV (fallbacks allowed).
+- `hard`: Required ENV at validation time (no fallback when empty/missing).
+- `deferred`: May be empty during early `verify`, but must resolve during `init-runtime` (from ENV or valid config/profile fallback).
 
 ### 4.2 `bootstrap`
 

docs/enshrouded_server.md

@@ -17,7 +17,7 @@ This document includes:
 | **saveDirectory** | Directory where savegames are stored | "./savegame" | File path (`ENSHROUDED_SAVE_DIR`) |
 | **logDirectory** | Directory for log files | "./logs" | File path (`ENSHROUDED_LOG_DIR`). Also hosts `server_manager.log` and `server_manager_backup/`. |
 | **ip** | Server IP binding | "0.0.0.0" | Server IPv4 address (`ENSHROUDED_IP`) |
-| **queryPort** | Port used for server queries | 15637 | Integer 1..65535 (`ENSHROUDED_QUERY_PORT`) |
+| **queryPort** | Port used for server queries | 15637 | Integer 1..65535 (`ENSHROUDED_QUERY_PORT`, `env_mode=deferred`: can initialize from ENV or config/profile fallback at runtime). |
 | **slotCount** | Max number of players | 16 | Integer 1..16 (`ENSHROUDED_SLOT_COUNT`) |
 | **tags** | Optional server browser tags | [] | Comma-separated tags in ENV (`ENSHROUDED_TAGS`), each tag: `A-Z a-z 0-9 . _ -` |
 | **voiceChatMode** | Voice chat type | Proximity | Proximity / Global (`ENSHROUDED_VOICE_CHAT_MODE`) |

docs/menu.md

@@ -44,6 +44,7 @@ Top-level selections:
 - `x` = Exit menu.
 - Prompts use `yes/no` (also accepts `y/n`).
 - `[ENV]` marks settings controlled by container environment variables (locked in the editors).
+- Fields with `env_mode=hard` and `env_mode=deferred` are treated as hard ENV-managed in the editors and cannot be changed there.
 
 Logging:
 

server_manager/jobs/env-validation

@@ -1179,7 +1179,7 @@ manager_profile_value_for_var() {
 }
 
 update_or_create_manager_config() {
-  local config_file profile value env_value var created_config env_mode env_is_set env_rule
+  local config_file profile value env_value var created_config env_mode env_is_set env_rule deferred_fallback_attempted
   created_config="false"
 
   if ! command -v jq >/dev/null 2>&1; then
@@ -1210,6 +1210,7 @@ update_or_create_manager_config() {
 
   while IFS= read -r var; do
     [[ -z "$var" ]] && continue
+    deferred_fallback_attempted="false"
     if ! validation_rule_json_read env_rule "$var"; then
       fatal "Validation unavailable for $var: ${VALIDATION_LAST_ERROR:-rule_lookup_failed}"
     fi
@@ -1241,13 +1242,21 @@ update_or_create_manager_config() {
     if [[ "$env_is_set" == "true" ]]; then
       if manager_value_is_valid "$var" "$env_value"; then
         value="$env_value"
+        if [[ "$env_mode" == "deferred" ]]; then
+          success "Resolved deferred runtime value for $var via ENV."
+        fi
       else
         fatal "Invalid ENV value for $var (actual: $env_value). ${VALIDATION_LAST_ERROR:-Validation failed.}"
       fi
     elif [[ "$env_mode" == "hard" ]]; then
       fatal "Missing required ENV $var (env_mode=hard). No fallback from config/profile is allowed."
     fi
 
+    if [[ -z "$value" && "$env_mode" == "deferred" ]]; then
+      warn "ENV $var is not available at this stage (env_mode=deferred). Trying config/profile fallback during init-runtime."
+      deferred_fallback_attempted="true"
+    fi
+
     # Fallback: active config -> profile template.
     if [[ -z "$value" && "$env_mode" != "hard" ]]; then
       value="$(manager_json_get "$config_file" "$var")"
@@ -1264,8 +1273,12 @@ update_or_create_manager_config() {
       fi
     fi
 
+    if [[ -n "$value" && "$env_mode" == "deferred" && "$deferred_fallback_attempted" == "true" ]]; then
+      info "Resolved deferred runtime value for $var via config/profile fallback."
+    fi
+
     if [[ -z "$value" && "$env_mode" == "deferred" ]]; then
-      fatal "Missing runtime value for $var (env_mode=deferred). Provide ENV or a valid config/profile fallback."
+      fatal "Missing runtime value for $var (env_mode=deferred): ENV not set and no valid config/profile fallback found."
     fi
 
     printf -v "$var" '%s' "$value"