build(deps): bump the patches group in /docs with 2 updates

Bumps the patches group in /docs with 2 updates: [click](https://github.com/pallets/click) and [zensical](https://github.com/zensical/zensical).


Updates `click` from 8.3.3 to 8.4.0
- [Release notes](https://github.com/pallets/click/releases)
- [Changelog](https://github.com/pallets/click/blob/main/CHANGES.rst)
- [Commits](https://github.com/pallets/click/compare/8.3.3...8.4.0)

Updates `zensical` from 0.0.41 to 0.0.43
- [Release notes](https://github.com/zensical/zensical/releases)
- [Commits](https://github.com/zensical/zensical/compare/v0.0.41...v0.0.43)

---
updated-dependencies:
- dependency-name: click
  dependency-version: 8.4.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: patches
- dependency-name: zensical
  dependency-version: 0.0.43
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: patches
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/dependabot.yml

@@ -13,6 +13,9 @@ updates:
           - minor
   - package-ecosystem: pip
     directory: "/docs"
+    labels:
+      - dependencies
+      - documentation
     schedule:
       interval: weekly
     groups:

.github/workflows/build.yml

@@ -85,14 +85,14 @@ jobs:
             baseImage: eclipse-temurin:8u312-b07-jre-focal
             platforms: linux/amd64,linux/arm/v7,linux/arm64
             mcVersion: 1.12.2
-            # Pin version for Java 8
-            mcHelperVersion: 1.51.1
+            # Pin version for Java 8, also be sure to set in verify-pr.yml
+            mcHelperVersion: 1.51.3-java8
           - variant: java8-jdk
             baseImage: eclipse-temurin:8u312-b07-jdk-focal
             platforms: linux/amd64,linux/arm64
             mcVersion: 1.12.2
-            # Pin version for Java 8
-            mcHelperVersion: 1.51.1
+            # Pin version for Java 8, also be sure to set in verify-pr.yml
+            mcHelperVersion: 1.51.3-java8
     env:
       IMAGE_TO_TEST: "${{ github.repository_owner }}/minecraft-server:test-${{ matrix.variant }}-${{ github.run_id }}"
       HAS_IMAGE_REPO_ACCESS: ${{ secrets.DOCKER_USER != '' && secrets.DOCKER_PASSWORD != '' }}

.github/workflows/verify-pr.yml

@@ -46,8 +46,8 @@ jobs:
             baseImage: eclipse-temurin:8u312-b07-jre-focal
             platforms: linux/amd64
             mcVersion: 1.12.2
-            # Pin version for Java 8
-            mcHelperVersion: 1.51.1
+            # Pin version for Java 8, be sure to also set in build.yml
+            mcHelperVersion: 1.51.3-java8
     env:
       IMAGE_TO_TEST: ${{ github.repository_owner }}/minecraft-server:test-${{ matrix.variant }}-${{ github.run_id }}
     runs-on: ubuntu-22.04

Dockerfile

@@ -26,36 +26,36 @@ ARG APPS_REV=1
 ARG GITHUB_BASEURL=https://github.com
 
 # renovate: datasource=github-releases packageName=itzg/easy-add
-ARG EASY_ADD_VERSION=0.8.11
+ARG EASY_ADD_VERSION=0.8.13
 ADD ${GITHUB_BASEURL}/itzg/easy-add/releases/download/${EASY_ADD_VERSION}/easy-add_${TARGETOS}_${TARGETARCH}${TARGETVARIANT} /usr/bin/easy-add
 RUN chmod +x /usr/bin/easy-add
 
 # renovate: datasource=github-releases packageName=itzg/restify
-ARG RESTIFY_VERSION=1.7.13
+ARG RESTIFY_VERSION=1.7.14
 RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
   --var version=${RESTIFY_VERSION} --var app=restify --file {{.app}} \
   --from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
 
 # renovate: datasource=github-releases packageName=itzg/rcon-cli
-ARG RCON_CLI_VERSION=1.7.4
+ARG RCON_CLI_VERSION=1.7.5
 RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
   --var version=${RCON_CLI_VERSION} --var app=rcon-cli --file {{.app}} \
   --from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
 
 # renovate: datasource=github-releases packageName=itzg/mc-monitor
-ARG MC_MONITOR_VERSION=0.16.2
+ARG MC_MONITOR_VERSION=0.16.4
 RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
   --var version=${MC_MONITOR_VERSION} --var app=mc-monitor --file {{.app}} \
   --from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
 
 # renovate: datasource=github-releases packageName=itzg/mc-server-runner
-ARG MC_SERVER_RUNNER_VERSION=1.14.5
+ARG MC_SERVER_RUNNER_VERSION=1.14.7
 RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
   --var version=${MC_SERVER_RUNNER_VERSION} --var app=mc-server-runner --file {{.app}} \
   --from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
 
 # renovate: datasource=github-releases packageName=itzg/mc-image-helper versioning=loose
-ARG MC_HELPER_VERSION=1.57.3
+ARG MC_HELPER_VERSION=1.58.0
 ARG MC_HELPER_BASE_URL=${GITHUB_BASEURL}/itzg/mc-image-helper/releases/download/${MC_HELPER_VERSION}
 # used for cache busting local copy of mc-image-helper
 ARG MC_HELPER_REV=1

docs/configuration/misc-options.md

@@ -22,6 +22,12 @@ docker run -d --pull=always \
     -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
 ```
 
+## Clean server libraries
+
+By default, supported server types remove stale server libraries during installation by setting `CLEAN_SERVER_LIBRARIES` to `true`. Set `CLEAN_SERVER_LIBRARIES` to `false` to disable this cleanup if it causes unexpected behavior.
+
+Currently, library cleanup is supported by `TYPE=PAPER`. Other server jar types are not yet supported.
+
 ## Running as alternate user/group ID
 
 By default, the container will switch to and run the Minecraft server as user ID 1000 and group ID 1000; however, that can be changed by setting the environment variables `UID` and `GID`.

docs/mods-and-plugins/index.md

@@ -156,6 +156,54 @@ 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, an entry inside an archive, or from the
+`.env` of each `GENERIC_PACK(S)` entry.
+
+- `LOAD_ENV_FROM_GENERIC_PACK`: when `true`, each entry in `GENERIC_PACKS` (after
+  `GENERIC_PACKS_PREFIX`/`SUFFIX` expansion) is probed for a top-level `.env`
+  and each one found is sourced in the same order the packs are applied (later
+  packs override earlier ones, matching the layering of the unpack itself). Packs
+  without a `.env` are skipped without error. URLs are downloaded into
+  `/data/packs/` and reused by the regular generic-pack unpack step, so they are
+  not fetched twice.
+- `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. The entry is sourced into the environment.
+- `LOAD_ENV_FROM_ARCHIVE_ENTRY`: relative path of the env file inside the archive.
+  Defaults to `.env`.
+
+These can be combined. Load order is: generic packs first, then
+`LOAD_ENV_FROM_FILE`, then `LOAD_ENV_FROM_ARCHIVE` — later loads override
+earlier ones, and all of them **override** values passed via `docker run -e` (or
+compose `environment:`), so the pack's declared values win.
+
+```shell
+docker run -d \
+  -e EULA=TRUE \
+  -e GENERIC_PACK=https://cdn.example.org/my-pack.zip \
+  -e LOAD_ENV_FROM_GENERIC_PACK=true \
+  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
+```
+
+!!! 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

docs/requirements.txt

@@ -1,4 +1,4 @@
-click==8.3.3
+click==8.4.0
 colorama==0.4.6
 deepmerge==2.0
 ghp-import==2.1.0
@@ -16,10 +16,10 @@ packaging==26.2
 pathspec==1.1.1
 platformdirs==4.9.6
 Pygments==2.20.0
-pymdown-extensions==10.21.2
+pymdown-extensions==10.21.3
 python-dateutil==2.9.0.post0
 PyYAML==6.0.3
 pyyaml_env_tag==1.1
 six==1.17.0
 watchdog==6.0.0
-zensical==0.0.40
+zensical==0.0.43

examples/vanilla-tweaks/docker-compose.yml

@@ -10,7 +10,6 @@ services:
       VANILLATWEAKS_FILE: /config/vanillatweaks-datapacks.json
       REMOVE_OLD_VANILLATWEAKS: "TRUE"
     volumes:
-      - data:/data
       - ./vanillatweaks-datapacks.json:/config/vanillatweaks-datapacks.json:ro
   vanillatweaks_sharecode:
     # port is set to 25566 to not conflict with vanillatweaks_file example
@@ -35,7 +34,6 @@ services:
       VANILLATWEAKS_FILE: /config/vanillatweaks-datapacks.json,/config/vanillatweaks-resourcepacks.json,/config/vanillatweaks-craftingtweaks.json
       REMOVE_OLD_VANILLATWEAKS: "TRUE"
     volumes:
-      - data:/data
       - ./vanillatweaks-datapacks.json:/config/vanillatweaks-datapacks.json:ro
       - ./vanillatweaks-resourcepacks.json:/config/vanillatweaks-resourcepacks.json:ro
-      - ./vanillatweaks-craftingtweaks.json:/config/vanillatweaks-craftingtweaks.json:ro
+      - ./vanillatweaks-craftingtweaks.json:/config/vanillatweaks-craftingtweaks.json:ro

scripts/start-configuration

@@ -152,6 +152,31 @@ 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.
+# Generic packs are processed first so that LOAD_ENV_FROM_FILE and
+# LOAD_ENV_FROM_ARCHIVE can override any values they set.
+
+if isTrue "${LOAD_ENV_FROM_GENERIC_PACK:-false}"; then
+  if ! loadEnvFromGenericPack; then
+    exit 1
+  fi
+fi
+
+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-deployPaper

@@ -11,17 +11,26 @@ handleDebugMode
 : "${PAPER_DOWNLOAD_URL:=}"
 : "${PAPER_CUSTOM_JAR:=}"
 : "${PAPER_CONFIG_DEFAULTS_REPO:=${PAPER_CONFIG_REPO:=https://raw.githubusercontent.com/Shonz1/minecraft-default-configs/main}}"
+: "${CLEAN_SERVER_LIBRARIES:=true}"
 
 resultsFile=/data/.paper.env
 if [[ $PAPER_CUSTOM_JAR ]]; then
   export SERVER="$PAPER_CUSTOM_JAR"
 elif [[ $PAPER_DOWNLOAD_URL ]]; then
-  if ! mc-image-helper install-paper \
-    --output-directory=/data \
-    --results-file="$resultsFile" \
-    --url="$PAPER_DOWNLOAD_URL"; then
-      logError "Failed to download from custom PaperMC URL"
-      exit 1
+
+  args=(
+    --output-directory=/data
+    --results-file="$resultsFile"
+    --url="$PAPER_DOWNLOAD_URL"
+  )
+
+  if [[ $CLEAN_SERVER_LIBRARIES ]]; then
+    args+=(--clean-libraries)
+  fi
+
+  if ! mc-image-helper install-paper "${args[@]}"; then
+    logError "Failed to download from custom PaperMC URL"
+    exit 1
   fi
   applyResultsFile ${resultsFile}
 else
@@ -35,6 +44,11 @@ else
   if [[ $PAPER_BUILD ]]; then
     args+=(--build="$PAPER_BUILD")
   fi
+
+  if [[ $CLEAN_SERVER_LIBRARIES ]]; then
+    args+=(--clean-libraries)
+  fi
+
   if ! mc-image-helper install-paper "${args[@]}"; then
       logError "Failed to download $PAPER_PROJECT"
       exit 1

scripts/start-utils

@@ -26,6 +26,117 @@ function applyResultsFile() {
   set +a
 }
 
+function loadEnvFromFile() {
+  local source=${1?Missing required source argument}
+  local downloaded=
+
+  if isURL "$source"; then
+    mkdir -p /data/.tmp
+    downloaded=$(mktemp -p /data/.tmp)
+    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
+
+  mkdir -p /data/.tmp
+
+  if isURL "$source"; then
+    downloaded=$(mktemp -p /data/.tmp)
+    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 -p /data/.tmp)
+  if extract "$archive" "$tmpdir" "$entry" && [ -f "$tmpdir/$entry" ]; then
+    log "Loading env vars from '$entry' in $source"
+    applyResultsFile "$tmpdir/$entry"
+  else
+    logError "Failed to load env entry '$entry' from $source"
+    rc=1
+  fi
+
+  rm -rf "$tmpdir"
+  [[ -n "$downloaded" ]] && rm -f "$downloaded"
+  return $rc
+}
+
+function loadEnvFromGenericPack() {
+  : "${GENERIC_PACKS:=${GENERIC_PACK:-}}"
+  : "${GENERIC_PACKS_PREFIX:=}"
+  : "${GENERIC_PACKS_SUFFIX:=}"
+
+  if [[ -z "${GENERIC_PACKS}" ]]; then
+    logWarning "LOAD_ENV_FROM_GENERIC_PACK is set but GENERIC_PACK(S) is empty"
+    return 0
+  fi
+
+  mkdir -p /data/.tmp
+  IFS=',' read -ra packs <<< "${GENERIC_PACKS}"
+  local loaded=0
+  local pack packEntry packFile tmpdir
+  for packEntry in "${packs[@]}"; do
+    pack="${GENERIC_PACKS_PREFIX}${packEntry}${GENERIC_PACKS_SUFFIX}"
+    if isURL "$pack"; then
+      mkdir -p /data/packs
+      if ! packFile=$(get -o /data/packs --output-filename --skip-up-to-date "$pack"); then
+        logError "Failed to download generic pack $pack"
+        return 1
+      fi
+    else
+      packFile=$pack
+    fi
+
+    if [[ ! -f "$packFile" ]]; then
+      logError "Generic pack not found: $packFile"
+      return 1
+    fi
+
+    tmpdir=$(mktemp -d -p /data/.tmp)
+    # Packs without a .env are valid — silently skip; the unpack step still applies them.
+    if extract "$packFile" "$tmpdir" .env 2>/dev/null && [ -f "$tmpdir/.env" ]; then
+      log "Loading env vars from .env in $pack"
+      applyResultsFile "$tmpdir/.env"
+      loaded=$((loaded + 1))
+    fi
+    rm -rf "$tmpdir"
+  done
+
+  if (( loaded == 0 )); then
+    logWarning "LOAD_ENV_FROM_GENERIC_PACK is set but no pack in GENERIC_PACK(S) contained a .env"
+  fi
+}
+
 function join_by() {
   local d=$1
   shift
@@ -445,17 +556,19 @@ function isType() {
 function extract() {
   src=${1?}
   destDir=${2?}
+  shift 2
+  # remaining args are paths within the archive to extract; if none, extract everything
 
   type=$(file -b --mime-type "${src}")
   case "${type}" in
   application/zip)
-    unzip -o -q -d "${destDir}" "${src}"
+    unzip -o -q -d "${destDir}" "${src}" "$@"
     ;;
   application/x-tar | application/gzip | application/x-gzip | application/x-bzip2)
-    tar -C "${destDir}" -xf "${src}"
+    tar -C "${destDir}" -xf "${src}" "$@"
     ;;
   application/zstd | application/x-zstd)
-    tar -C "${destDir}" --use-compress-program=unzstd -xf "${src}"
+    tar -C "${destDir}" --use-compress-program=unzstd -xf "${src}" "$@"
     ;;
   *)
     logError "Unsupported archive type: $type"

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/verify.sh

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

tests/setuponlytests/load-env-from-file/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_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-file/load-env.env

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

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

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

tests/setuponlytests/load-env-from-generic-pack/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  mc:
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "true"
+      SETUP_ONLY: "true"
+      GENERIC_PACK: /packs/pack.zip
+      LOAD_ENV_FROM_GENERIC_PACK: "true"
+      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
+      - ./pack.zip:/packs/pack.zip
+      - ./fake.jar:/servers/fake.jar

tests/setuponlytests/load-env-from-generic-pack/verify.sh

@@ -0,0 +1,2 @@
+mc-image-helper assert propertyEquals --file=server.properties --property=motd --expect=from-generic-pack
+mc-image-helper assert fileExists config/dummy.yml