Add PRE_START_SCRIPT, run after setup and before the server starts (#4293)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/build.yml

@@ -166,7 +166,7 @@ jobs:
         uses: docker/setup-buildx-action@v4
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4.3.0
+        uses: docker/setup-qemu-action@v4.4.0
 
       - name: Build for test
         uses: docker/build-push-action@v7

.github/workflows/discord.yml

@@ -1,43 +0,0 @@
-name: Discord notifications
-
-on:
-  release:
-    types:
-      - published
-  workflow_run:
-    workflows: ["Build and Publish"]
-    types:
-      - completed
-
-env:
-  DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
-
-jobs:
-  discord:
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    if: github.repository_owner == 'itzg'
-    steps:
-      - name: on-publish
-        if: github.event_name == 'release' && github.event.action == 'published'
-        uses: SethCohen/github-releases-to-discord@v1.20.0
-        with:
-          webhook_url: ${{ secrets.DISCORD_WEBHOOK }}
-      - name: on-success
-        if: github.event.workflow_run.conclusion == 'success'
-        uses: Ilshidur/action-discord@master
-        with:
-          args: |
-            Github repo: ${{ github.repository }}
-            - Branch: ${{ github.event.workflow_run.head_branch }}
-            - [Link: to Actions](<${{ github.event.workflow_run.html_url }}>)
-            - Status: 🎉  ${{ github.event.workflow_run.conclusion }}  🍏
-      - name: on-failure
-        if: github.event.workflow_run.conclusion == 'failure'
-        uses: Ilshidur/action-discord@master
-        with:
-          args: |
-            Github repo: ${{ github.repository }}
-            - Branch: ${{ github.event.workflow_run.head_branch }}
-            - [Link: to Actions](<${{ github.event.workflow_run.html_url }}>)
-            - Status: 🤔  ${{ github.event.workflow_run.conclusion }}  💣💥

.github/workflows/verify-pr.yml

@@ -76,7 +76,7 @@ jobs:
         uses: docker/setup-buildx-action@v4
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4.3.0
+        uses: docker/setup-qemu-action@v4.4.0
 
       - name: Confirm multi-arch build
         uses: docker/build-push-action@v7

Dockerfile

@@ -45,19 +45,19 @@ RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
   --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.17.1
+ARG MC_MONITOR_VERSION=0.18.1
 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.15.2
+ARG MC_SERVER_RUNNER_VERSION=1.16.0
 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.68.0
+ARG MC_HELPER_VERSION=1.70.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

@@ -209,6 +209,22 @@ By default, the image finishes startup by exec'ing [mc-server-runner](https://gi
 > [!TIP]
 > The `SERVER_RUNNER` variable is expanded when passed to `exec` so that `mc-server-runner` can be wrapped by another executable that is mounted into the container.
 
+## Pre-start script
+
+To run something of your own after the image has finished setting up the server files and just before it starts the server, set `PRE_START_SCRIPT` to the path of an executable file that you have mounted into the container. The image runs it directly (not through a shell) and waits for it to finish. It runs as the user the server runs as, from the server's working directory, with the same environment the server gets. If it exits with a non-zero status, the container exits without starting the server.
+
+For example, a script that waits for plugin jars that another process is still downloading:
+
+```yaml
+    environment:
+      PRE_START_SCRIPT: /hooks/wait-for-plugins
+    volumes:
+      - ./hooks:/hooks:ro
+```
+
+> [!WARNING]
+> The image does not guarantee that any particular command is available to the script, and it may change between image versions. Keeping the script working is up to you.
+
 ## Enable Flare Flags
     
 To enable the JVM flags required to fully support the [Flare profiling suite](https://blog.airplane.gg/flare), set the following variable:

docs/mods-and-plugins/index.md

@@ -66,6 +66,8 @@ You can also specify the `REMOVE_OLD_MODS_DEPTH` (default is 16) variable to onl
 
 For example: `-e REMOVE_OLD_MODS=TRUE -e REMOVE_OLD_MODS_INCLUDE="*.jar" -e REMOVE_OLD_MODS_DEPTH=1` will remove all old jar files that are directly inside the `plugins/` or `mods/` directory.
 
+To remove all files in the `/data/config` directory before a modpack is downloaded and unpacked, set `REMOVE_OLD_CONFIGS=TRUE`. This is useful when a modpack update would otherwise override locally customized configuration files. The removal process can be fine tuned with `REMOVE_OLD_CONFIGS_INCLUDE` and `REMOVE_OLD_CONFIGS_EXCLUDE` (comma separated lists of file glob patterns, defaults to `*` so everything is removed) and `REMOVE_OLD_CONFIGS_DEPTH` (default 16). The target directory can be changed with `CONFIG_OUT_DIR` (default `/data/config`).
+
 These paths work well if you want to have a common set of modules in a separate location, but still have multiple worlds with different server requirements in either persistent volumes or a downloadable archive.
 
 !!! information "Multiple source directories"

docs/requirements.txt

@@ -14,12 +14,12 @@ mkdocstrings==1.0.6
 mkdocstrings-python==2.0.8
 packaging==26.3
 pathspec==1.1.1
-platformdirs==4.11.7
+platformdirs==4.11.11
 Pygments==2.21.0
-pymdown-extensions==11.0.2
+pymdown-extensions==12.0.1
 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.59
+zensical==0.0.63

docs/variables.md

@@ -288,6 +288,12 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
             <td><code>false</code></td>
             <td>⬜️</td>
         </tr>
+        <tr>
+            <td><code>PRE_START_SCRIPT</code></td>
+            <td>Path to an executable run after setup and just before the server starts. The server is not started if it exits non-zero. See <a href="../configuration/misc-options/#pre-start-script">Pre-start script</a></td>
+            <td><code></code></td>
+            <td>⬜️</td>
+        </tr>
         <tr>
             <td><code>USE_FLARE_FLAGS</code></td>
             <td>To enable the JVM flags required to fully support the <a href="https://blog.airplane.gg/flare">Flare profiling suite</a>.</td>

files/cf-exclude-include.json

@@ -177,6 +177,7 @@
     "yungs-menu-tweaks",
     "zume"
   ],
+  "globalForceIncludes": ["simply-tooltips"],
   "modpacks": {
     "all-of-fabric-6": {
       "forceIncludes": ["revelationary"]
@@ -188,7 +189,7 @@
       "forceIncludes": ["just-enough-resources-jer"]
     },
     "fantasy-minecraft-fabric": {
-      "forceIncludes": ["simply-tooltips", "icon-leading-tooltip"]
+      "forceIncludes": ["icon-leading-tooltip"]
     },
     "ftb-stoneblock-4": {
       "forceIncludes": [

files/modrinth-exclude-include.json

@@ -105,7 +105,7 @@
     "Zoomify",
     "zume"
   ],
-  "globalForceIncludes": [],
+  "globalForceIncludes": ["/(^|/)simplytooltips-/", "/(^|/)s-lib-/"],
   "modpacks": {
     "cobbleverse": {
       "excludes": [

scripts/start-configuration

@@ -36,7 +36,7 @@ if isTrue "$PREFER_IPV6"; then
   export JVM_DD_OPTS
 fi
 
-if (( $(mc-image-helper java-release) >= 17 )); then
+if (( $(getJavaRelease) >= 17 )); then
   MC_IMAGE_HELPER_OPTS+=" --enable-native-access=ALL-UNNAMED"
   export MC_IMAGE_HELPER_OPTS
 fi

scripts/start-finalExec

@@ -4,10 +4,27 @@
 : "${SETUP_ONLY:=false}"
 : "${CUSTOM_JAR_EXEC:=}"
 : "${SERVER_RUNNER:=mc-server-runner}"
+: "${PRE_START_SCRIPT:=}"
 
 # shellcheck source=start-utils
 . "$(dirname "$0")/start-utils"
 isDebugging && set -x
+
+function runPreStartScript() {
+  if [[ ! $PRE_START_SCRIPT ]]; then
+    return
+  fi
+  if [[ ! -x $PRE_START_SCRIPT ]]; then
+    logError "PRE_START_SCRIPT $PRE_START_SCRIPT is not an executable file"
+    exit 1
+  fi
+  log "Running pre-start script $PRE_START_SCRIPT..."
+  if ! "$PRE_START_SCRIPT"; then
+    logError "Pre-start script $PRE_START_SCRIPT failed, so the server will not be started"
+    exit 1
+  fi
+}
+
 baseDataDir=/data
 tmpServerIconPath=/tmp/icon.img
 serverIconPath=${baseDataDir}/server-icon.png
@@ -505,6 +522,7 @@ if [[ ${TYPE} == "CURSEFORGE" && "${SERVER}" ]]; then
     exit 1
   fi
   log "Starting CurseForge server in ${FTB_DIR}..."
+  runPreStartScript
   if isTrue "${DEBUG_EXEC}"; then
     set -x
   fi
@@ -569,6 +587,7 @@ fi
       JVM_ARGS=${JVM_ARGS//$'\n'/}
       sed -i "s~JAVA_ARGS=.*~JAVA_ARGS=\"${JVM_ARGS}\"~" "${FTB_DIR}/variables.txt"
   fi
+  runPreStartScript
   exec ${SERVER_RUNNER} "${mcServerRunnerArgs[@]}" -- "${finalArgs[@]}"
 elif [[ $SERVER =~ run.sh ]]; then
   log "Using Forge supplied run.sh script..."
@@ -577,6 +596,7 @@ elif [[ $SERVER =~ run.sh ]]; then
     echo "SETUP_ONLY: bash ${SERVER}"
     exit
   fi
+  runPreStartScript
   if isTrue "${DEBUG_EXEC}"; then
     set -x
   fi
@@ -614,6 +634,7 @@ else
     exit
   fi
 
+  runPreStartScript
   if isTrue "${DEBUG_EXEC}"; then
     set -x
   fi

scripts/start-setupModpack

@@ -9,6 +9,11 @@ set -e -o pipefail
 : "${PLUGINS_FILE:=}"
 : "${REMOVE_OLD_MODS_DEPTH:=1} "
 : "${REMOVE_OLD_MODS_INCLUDE:=*.jar,*-version.json}"
+: "${REMOVE_OLD_CONFIGS:=false}"
+: "${CONFIG_OUT_DIR:=/data/config}"
+: "${REMOVE_OLD_CONFIGS_DEPTH:=16}"
+: "${REMOVE_OLD_CONFIGS_INCLUDE:=*}"
+: "${REMOVE_OLD_CONFIGS_EXCLUDE:=}"
 : "${CF_USE_HTTP2:=false}" # CF downloads are faster with HTTP 1.1
 : "${MODRINTH_LOADER:=}"
 
@@ -25,6 +30,10 @@ if isTrue "${REMOVE_OLD_MODS}" && [ -z "${MODS_FILE}" ]; then
   rm -f "$sum_file"
 fi
 
+if isTrue "${REMOVE_OLD_CONFIGS}"; then
+  removeOldConfigs "$CONFIG_OUT_DIR"
+fi
+
 function handlePackwiz() {
   # If packwiz url passed, bootstrap packwiz and update mods before other modpack processing
   if [[ "${PACKWIZ_URL:-}" ]]; then

scripts/start-utils

@@ -547,6 +547,23 @@ function removeOldMods {
   fi
 }
 
+function removeOldConfigs {
+  if [ -d "$1" ]; then
+    log "Removing old configs including='${REMOVE_OLD_CONFIGS_INCLUDE}' excluding='${REMOVE_OLD_CONFIGS_EXCLUDE}' up to depth=${REMOVE_OLD_CONFIGS_DEPTH}"
+    args=(
+      --delete
+      --type file
+      --min-depth=1 --max-depth "${REMOVE_OLD_CONFIGS_DEPTH}"
+      --name "${REMOVE_OLD_CONFIGS_INCLUDE}"
+      --exclude-name "${REMOVE_OLD_CONFIGS_EXCLUDE}"
+    )
+    if ! isDebugging; then
+      args+=(--quiet)
+    fi
+    mc-image-helper find "${args[@]}" "$1"
+  fi
+}
+
 function get() {
   mc-image-helper get "$@"
 }
@@ -629,6 +646,23 @@ function getDistro() {
   grep -E "^ID=" /etc/os-release | cut -d= -f2 | sed -e 's/"//g'
 }
 
+function getJavaRelease() {
+  # Read the major version from the JDK's release file so no JVM has to start;
+  # the helper is the fallback when the file is missing.
+  local version
+  if [[ ${JAVA_HOME:-} && -f "$JAVA_HOME/release" ]]; then
+    version=$(sed -n -e 's/^JAVA_VERSION="\(.*\)"$/\1/p' "$JAVA_HOME/release")
+    # Java 8 and earlier report 1.8.0_312 and so on
+    version=${version#1.}
+    version=${version%%[._-]*}
+  fi
+  if isNumeric "${version:-}"; then
+    echo "$version"
+  else
+    mc-image-helper java-release
+  fi
+}
+
 function checkSum() {
   local sum_file=${1?}
 

tests/setuponlytests/remove-old-configs/docker-compose.yml

@@ -0,0 +1,43 @@
+services:
+  # copies an existing config into /data before mc starts, so REMOVE_OLD_CONFIGS
+  # has an old config to remove once the modpack config is installed
+  seed:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    entrypoint: ["bash", "-c", "mkdir -p /data/config && cp /seed/config/stale.txt /data/config/ && chown -R 1000:1000 /data"]
+    volumes:
+      - ./seed:/seed
+      - ./data:/data
+
+  web:
+    image: nginx
+    volumes:
+      - ./configs.zip:/usr/share/nginx/html/configs.zip:ro
+    healthcheck:
+      test: ["CMD", "curl", "--fail", "http://localhost/configs.zip"]
+      interval: 3s
+      timeout: 5s
+      retries: 3
+
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    depends_on:
+      seed:
+        condition: service_completed_successfully
+      web:
+        condition: service_healthy
+    environment:
+      EULA: "true"
+      SETUP_ONLY: "true"
+      GENERIC_PACKS: http://web/configs.zip
+      REMOVE_OLD_CONFIGS: "true"
+      LOG_TIMESTAMP: "true"
+      # the following are only used to speed up test execution
+      TYPE: CUSTOM
+      CUSTOM_SERVER: /servers/fake.jar
+      VERSION: 1.18.1
+      DEBUG: "true"
+    volumes:
+      - ./data:/data
+      - ./fake.jar:/servers/fake.jar

tests/setuponlytests/remove-old-configs/seed/config/stale.txt

@@ -0,0 +1 @@
+old

tests/setuponlytests/remove-old-configs/verify.sh

@@ -0,0 +1,3 @@
+# verify that the old config was removed and the new one from the pack was installed
+mc-image-helper assert fileNotExists config/stale.txt
+mc-image-helper assert fileExists config/opt.yml