feat: load env vars from file or archive at startup

Adds LOAD_ENV_FROM_FILE and LOAD_ENV_FROM_ARCHIVE so a generic pack or
artifact can ship its own container configuration (TYPE, VERSION, etc.)
inside-out. Loaded values override anything passed via docker -e, and
the load runs in start-configuration after proxy/Java setup but before
TYPE is dispatched, so the loaded TYPE drives the deploy step.

LOAD_ENV_FROM_ARCHIVE_ENTRY selects the file inside the archive
(default: .env). EULA is intentionally NOT loadable this way since the
EULA check runs earlier.

Closes #4037

Author: ChipWolf

docs/mods-and-plugins/index.md

@@ -156,6 +156,46 @@ Disabling mods within docker compose files:
         mod2.jar
 ```
 
+### Loading container configuration from a pack
+
+A pack can ship its own container configuration so that the server type, version,
+and other variables travel with the pack rather than being declared by the user.
+At startup, before `TYPE` is dispatched, the container can load environment
+variables from a file on disk, a URL, or a file inside an archive (URL or local).
+
+- `LOAD_ENV_FROM_FILE`: container path or URL of a shell-style env file (one
+  `KEY=VALUE` per line). Comments and blank lines are allowed.
+- `LOAD_ENV_FROM_ARCHIVE`: container path or URL of a zip/tar archive containing
+  an env file. Each entry is sourced into the environment.
+- `LOAD_ENV_FROM_ARCHIVE_ENTRY`: relative path of the env file inside the archive.
+  Defaults to `.env`.
+
+Both `LOAD_ENV_FROM_FILE` and `LOAD_ENV_FROM_ARCHIVE` may be set at the same time;
+the file is loaded first, then the archive entry. Values loaded from these sources
+**override** anything passed via `docker run -e` (or compose `environment:`), so
+the pack's declared values win.
+
+```shell
+docker run -d \
+  -e EULA=TRUE \
+  -e LOAD_ENV_FROM_ARCHIVE=https://cdn.example.org/my-pack.zip \
+  itzg/minecraft-server
+```
+
+Where `my-pack.zip` contains a `.env` at its root such as:
+
+```env
+TYPE=FABRIC
+VERSION=1.21.1
+FABRIC_LOADER_VERSION=0.16.0
+GENERIC_PACK=https://cdn.example.org/my-pack.zip
+```
+
+!!! warning
+    The env file is sourced by `bash`, so any shell syntax it contains will be
+    evaluated. Only point these variables at sources you trust. `EULA` cannot be
+    set this way — it is checked before the env file is loaded.
+
 ## Mods/plugins list
 
 You may also download or copy over individual mods/plugins using the `MODS` or `PLUGINS` environment variables. Both are a comma or newline delimited list of

scripts/start-configuration

@@ -152,6 +152,23 @@ fi
 
 cd /data || exit 1
 
+##########################################
+# Optionally load environment variables from a file or archive entry,
+# allowing packs/artifacts to declare TYPE, VERSION and other settings
+# inside-out. Loaded values override anything passed in through docker -e.
+
+if [[ ${LOAD_ENV_FROM_FILE:-} ]]; then
+  if ! loadEnvFromFile "${LOAD_ENV_FROM_FILE}"; then
+    exit 1
+  fi
+fi
+
+if [[ ${LOAD_ENV_FROM_ARCHIVE:-} ]]; then
+  if ! loadEnvFromArchive "${LOAD_ENV_FROM_ARCHIVE}" "${LOAD_ENV_FROM_ARCHIVE_ENTRY:-.env}"; then
+    exit 1
+  fi
+fi
+
 export DECLARED_TYPE=${TYPE^^}
 export DECLARED_VERSION="$VERSION"
 

scripts/start-utils

@@ -26,6 +26,71 @@ function applyResultsFile() {
   set +a
 }
 
+function loadEnvFromFile() {
+  local source=${1?Missing required source argument}
+  local downloaded=
+
+  if isURL "$source"; then
+    downloaded=$(mktemp)
+    log "Downloading env file from $source"
+    if ! get -o "$downloaded" "$source"; then
+      logError "Failed to download env file from $source"
+      rm -f "$downloaded"
+      return 1
+    fi
+    log "Loading env vars from $source"
+    applyResultsFile "$downloaded"
+    rm -f "$downloaded"
+  elif [ -f "$source" ]; then
+    log "Loading env vars from $source"
+    applyResultsFile "$source"
+  else
+    logError "Env file not found: $source"
+    return 1
+  fi
+}
+
+function loadEnvFromArchive() {
+  local source=${1?Missing required source argument}
+  local entry=${2:-.env}
+  local archive=
+  local downloaded=
+  local tmpdir
+  local rc=0
+
+  if isURL "$source"; then
+    downloaded=$(mktemp)
+    log "Downloading archive from $source"
+    if ! get -o "$downloaded" "$source"; then
+      logError "Failed to download archive from $source"
+      rm -f "$downloaded"
+      return 1
+    fi
+    archive=$downloaded
+  elif [ -f "$source" ]; then
+    archive=$source
+  else
+    logError "Archive not found: $source"
+    return 1
+  fi
+
+  tmpdir=$(mktemp -d)
+  if ! extract "$archive" "$tmpdir"; then
+    logError "Failed to extract $source"
+    rc=1
+  elif [ ! -f "$tmpdir/$entry" ]; then
+    logError "Entry '$entry' not found in archive $source"
+    rc=1
+  else
+    log "Loading env vars from '$entry' in $source"
+    applyResultsFile "$tmpdir/$entry"
+  fi
+
+  rm -rf "$tmpdir"
+  [[ -n "$downloaded" ]] && rm -f "$downloaded"
+  return $rc
+}
+
 function join_by() {
   local d=$1
   shift

tests/setuponlytests/load-env-from-archive/docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+  mc:
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "true"
+      SETUP_ONLY: "true"
+      LOAD_ENV_FROM_ARCHIVE: /test/load-env.zip
+      MOTD: from-compose
+      LOG_TIMESTAMP: "true"
+      DEBUG: "true"
+      # the following are only used to speed up test execution
+      TYPE: CUSTOM
+      CUSTOM_SERVER: /servers/fake.jar
+      VERSION: 1.18.1
+    volumes:
+      - ./data:/data
+      - ./load-env.zip:/test/load-env.zip
+      - ./fake.jar:/servers/fake.jar

tests/setuponlytests/load-env-from-archive/fake.jar

@@ -0,0 +1 @@
+mc-image-helper assert propertyEquals --file=server.properties --property=motd --expect=from-archive

tests/setuponlytests/load-env-from-archive/load-env.zip

@@ -0,0 +1,18 @@
+services:
+  mc:
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "true"
+      SETUP_ONLY: "true"
+      LOAD_ENV_FROM_FILE: /test/load-env.env
+      MOTD: from-compose
+      LOG_TIMESTAMP: "true"
+      DEBUG: "true"
+      # the following are only used to speed up test execution
+      TYPE: CUSTOM
+      CUSTOM_SERVER: /servers/fake.jar
+      VERSION: 1.18.1
+    volumes:
+      - ./data:/data
+      - ./load-env.env:/test/load-env.env
+      - ./fake.jar:/servers/fake.jar

tests/setuponlytests/load-env-from-archive/verify.sh

@@ -0,0 +1,2 @@
+# Loaded by LOAD_ENV_FROM_FILE during start-configuration
+MOTD=from-env-file