Add release selection for the GitHub-released server types (#4339)

.github/workflows/build.yml

@@ -94,25 +94,25 @@ jobs:
             platforms: linux/amd64,linux/arm/v7,linux/arm64
             mcVersion: 1.16.5
             # Pin version for pre-Java 17
-            mcHelperVersion: 1.51.4-java8
+            mcHelperVersion: 1.51.5-java8
         # JAVA 11
           - variant: java11
             baseImage: adoptopenjdk:11-jre-hotspot
             platforms: linux/amd64,linux/arm/v7,linux/arm64
             mcVersion: 1.16.4
             # Pin version for pre-Java 17
-            mcHelperVersion: 1.51.4-java8
+            mcHelperVersion: 1.51.5-java8
         # JAVA 8: NOTE: Unable to go past 8u312 because of Forge dependencies
           - variant: java8
             baseImage: eclipse-temurin:8-jre
             platforms: linux/amd64,linux/arm/v7,linux/arm64
             mcVersion: 1.12.2
-            mcHelperVersion: 1.51.4-java8
+            mcHelperVersion: 1.51.5-java8
           - variant: java8-jdk
             baseImage: eclipse-temurin:8-jdk
             platforms: linux/amd64,linux/arm64
             mcVersion: 1.12.2
-            mcHelperVersion: 1.51.4-java8
+            mcHelperVersion: 1.51.5-java8
     env:
       # Assume they line up, but when forked change to your Docker Hub username
       DOCKER_HUB_ORG: ${{ github.repository_owner }}

.github/workflows/verify-pr.yml

@@ -62,7 +62,7 @@ jobs:
             # For GLIBC_2.34 support
             knockdRepoOrg: Metalcape/knock
             # Pin version for Java 8, be sure to also set in build.yml
-            mcHelperVersion: 1.51.4-java8
+            mcHelperVersion: 1.51.5-java8
     env:
       IMAGE_TO_TEST: ${{ github.repository_owner }}/minecraft-server:test-${{ matrix.variant }}-${{ github.run_id }}
     runs-on: ubuntu-22.04

docs/types-and-platforms/server-types/hybrids.md

@@ -35,6 +35,8 @@ There are limited base versions supported, so you will also need to  set `VERSIO
 Available Ketting Versions may be found at [https://reposilite.c0d3m4513r.com/#/Ketting-Server-Releases/org/kettingpowered/server/forge](https://reposilite.c0d3m4513r.com/#/Ketting-Server-Releases/org/kettingpowered/server/forge).
 The Version structure is `MinecraftVersion-ForgeVersion-KettingVersion` (e.g. `1.20.1-47.2.20-0.1.4` is for Minecraft `1.20.1`, Forge `47.2.20` and Ketting `0.1.4`).
 
+The launcher itself defaults to the latest release; set `KETTING_RELEASE` to a [specific release](https://github.com/kettingpowered/kettinglauncher/releases) tag, such as `v1.5.1`, to download that one instead.
+
 ### Mohist
 
 A [Mohist](https://github.com/MohistMC/Mohist) server can be used with
@@ -83,3 +85,5 @@ A [Arclight](https://arclight.izzel.io/) type server can be used with
 
     -e TYPE=ARCLIGHT
     -e ARCLIGHT_TYPE=NEOFORGE,FORGE,FABRIC
+
+By default the latest release is used; set `ARCLIGHT_RELEASE` to a [specific release](https://github.com/IzzelAliz/Arclight/releases) tag, such as `FeudalKings/1.0.1`, to run that one instead. A `VERSION` is still required to select the matching jar within the release.

docs/types-and-platforms/server-types/others.md

@@ -47,6 +47,28 @@ Note: it is a fork of the original [NanoLimbo](https://github.com/Nan1t/NanoLimb
 
 An alternate Limbo server
 
+Configuration options with defaults:
+
+- `NANOLIMBO_RELEASE`=latest
+
+  The [NanoLimbo release](https://github.com/BoomEaro/NanoLimbo/releases) to download the server jar from, such as `1.13.0`.
+
+## Poseidon
+
+A [Poseidon](https://github.com/retromcorg/Project-Poseidon) server can be run by setting `TYPE` to `POSEIDON`.
+
+Poseidon is only available for b1.7.3, so be sure to set `VERSION=b1.7.3`.
+
+Configuration options with defaults:
+
+- `POSEIDON_RELEASE`=latest
+
+  The [Poseidon release](https://github.com/retromcorg/Project-Poseidon/releases) to download, such as `1.1.12-260720-1033-5303bd5`.
+
+- `POSEIDON_TYPE`=poseidon
+
+  Set to `uberbukkit` to use the [uberbukkit](https://github.com/Moresteck/uberbukkit) fork instead, whose releases are also selectable with `POSEIDON_RELEASE`.
+
 ## Crucible
 
 A [Crucible](https://github.com/CrucibleMC/Crucible) server can be run by setting `TYPE` to `CRUCIBLE`.
@@ -55,6 +77,8 @@ Configuration options with defaults:
 
 - `CRUCIBLE_RELEASE`=latest
 
+  The [Crucible release](https://github.com/CrucibleMC/Crucible/releases) to run, such as `v5.4`. Since `latest` only tracks full releases, a pre-release such as a `staging-*` tag has to be named explicitly.
+
 Crucible is only available for 1.7.10, so be sure to set `VERSION=1.7.10`.
 
 ## Custom
@@ -79,7 +103,7 @@ Alternatively, the final `-jar` invocation can be replaced by setting `CUSTOM_JA
 
 A [Pumpkin](https://pumpkinmc.org/) server can be run by setting `TYPE` to `PUMPKIN`.
 
-Pumpkin is a Minecraft server written in Rust and is shipped as a single native executable instead of a Java jar. The image downloads the asset matching its architecture from the [latest release](https://github.com/Pumpkin-MC/Pumpkin/releases), so `VERSION` and the JVM memory and tuning variables do not apply.
+Pumpkin is a Minecraft server written in Rust and is shipped as a single native executable instead of a Java jar. The image downloads the asset matching its architecture from the [latest release](https://github.com/Pumpkin-MC/Pumpkin/releases), so `VERSION` and the JVM memory and tuning variables do not apply. Set `PUMPKIN_RELEASE` to run a different release.
 
 ```shell
 docker run -d --pull=always -v /path/on/host:/data \
@@ -93,6 +117,12 @@ Configuration options with defaults:
 
   Set to true to re-download the executable.
 
+- `PUMPKIN_RELEASE`=latest
+
+  The [Pumpkin release](https://github.com/Pumpkin-MC/Pumpkin/releases) to run, such as `0.2.0+26.3-26.51`, or a moving prerelease channel like `nightly` or `canary`. `VERSION` selects the Minecraft version for other server types, so it is ignored here.
+
+  Each release is downloaded to `/data/pumpkin-<arch>-Linux`, and switching `PUMPKIN_RELEASE` replaces that executable. Set `FORCE_REDOWNLOAD=true` to re-download the selected release, which is useful to pick up a newer `nightly` or `canary` build.
+
 Pumpkin is configured through `/data/pumpkin.toml`. The image creates that file on the first run and updates the settings below at each startup, leaving the remaining options in your file alone. Anything without a matching environment variable can be set by editing `pumpkin.toml` directly.
 
 | Variable                                            | Pumpkin setting                                                                    |

examples/ketting/docker-compose.yml

@@ -5,6 +5,8 @@ services:
       EULA: true
       TYPE: KETTING
       VERSION: 1.20.1
+      # Optionally pin a specific Ketting launcher release instead of the latest
+      # KETTING_RELEASE: "v1.5.1"
       CURSEFORGE_FILES: https://www.curseforge.com/minecraft/mc-mods/aquaculture
     ports:
       - "25565:25565"

examples/pumpkin/compose.yml

@@ -6,6 +6,8 @@ services:
     environment:
       EULA: "true"
       TYPE: PUMPKIN
+      # Optionally pin a specific Pumpkin release instead of the latest
+      # PUMPKIN_RELEASE: "0.2.0+26.3-26.51"
     ports:
       - "25565:25565"
       - "19132:19132/udp"

scripts/start-deployArcLight

@@ -10,27 +10,22 @@ resolveVersion
 : "${ARCLIGHT_RELEASE:=latest}"
 : "${ARCLIGHT_TYPE:=neoforge}"
 
-arclightReleasesUrl=https://api.github.com/repos/IzzelAliz/Arclight/releases
+# An omitted --release-tag means the latest release, so only pass it when a
-if [[ ${ARCLIGHT_RELEASE^^} = LATEST ]]; then
+# specific release was requested
-  arclightReleaseUrl=${arclightReleasesUrl}/latest
+arclightReleaseArgs=()
-else
+[[ ${ARCLIGHT_RELEASE} == latest ]] || arclightReleaseArgs+=(--release-tag="${ARCLIGHT_RELEASE}")
-  arclightReleaseUrl=${arclightReleasesUrl}/tags/${ARCLIGHT_RELEASE}
-fi
 
-if ! downloadUrl=$(get --json-path "$.assets[?(@.name =~ /arclight-${ARCLIGHT_TYPE,,}-${VERSION}-.*\.jar/)].browser_download_url" \
+arclightRepo=IzzelAliz/Arclight
-    --accept "application/vnd.github.v3+json" "$arclightReleaseUrl"); then
-  logError "Failed to access ${ARCLIGHT_RELEASE} release of Arclight"
-  exit 1
-fi
 
-if [[ $downloadUrl = null ]]; then
+log "Downloading Arclight ${VERSION} ${ARCLIGHT_TYPE,,} from the ${ARCLIGHT_RELEASE} release"
-  logError "Failed to locate Arclight jar for $VERSION from ${ARCLIGHT_RELEASE}"
+if ! SERVER=$(mc-image-helper github download-asset \
-  exit 1
+  "${arclightReleaseArgs[@]}" \
-fi
+  --output-directory=/data \
-
+  --name-pattern="^arclight-${ARCLIGHT_TYPE,,}-${VERSION}-.+\.jar$" \
-log "Downloading Arclight from $downloadUrl"
+  ${arclightRepo}
-if ! SERVER=$(get --skip-existing --output-filename -o /data "$downloadUrl"); then
+  ); then
-  logError "Arclight jar from $downloadUrl"
+  logError "Failed to download Arclight jar for ${VERSION} from the ${ARCLIGHT_RELEASE} release"
+  logError "Ensure ARCLIGHT_RELEASE is one of the releases at ${arclightReleasesUrl}"
   exit 1
 fi
 

scripts/start-deployCrucible

@@ -9,49 +9,43 @@ isDebugging && set -x
 resolveVersion
 : "${CRUCIBLE_RELEASE:=latest}"
 
-crucibleReleasesUrl=https://api.github.com/repos/CrucibleMC/Crucible/releases
+# An omitted --release-tag means the latest release, so only pass it when a
-if [[ ${CRUCIBLE_RELEASE^^} = LATEST ]]; then
+# specific release was requested
-  crucibleReleaseUrl=${crucibleReleasesUrl}/latest
+crucibleReleaseArgs=()
-else
+[[ ${CRUCIBLE_RELEASE} == latest ]] || crucibleReleaseArgs+=(--release-tag="${CRUCIBLE_RELEASE}")
-  crucibleReleaseUrl=${crucibleReleasesUrl}/tags/${CRUCIBLE_RELEASE}
-fi
 
-if ! downloadUrl=$(get --json-path "$.assets[?(@.name =~ /Crucible-${VERSION}-.*\.jar/)].browser_download_url" \
+crucibleRepo=CrucibleMC/Crucible
-    --accept "application/vnd.github.v3+json" "$crucibleReleaseUrl"); then
-  logError "Failed to access ${CRUCIBLE_RELEASE} release of Crucible"
-  exit 1
-fi
 
-if [[ $downloadUrl = null ]]; then
+log "Downloading Crucible ${VERSION} from the ${CRUCIBLE_RELEASE} release"
-  logError "Failed to locate Crucible jar for $VERSION from ${CRUCIBLE_RELEASE}"
+if ! SERVER=$(mc-image-helper github download-asset \
-  exit 1
+  "${crucibleReleaseArgs[@]}" \
-fi
+  --output-directory=/data \
-
+  --name-pattern="^Crucible-${VERSION}-.+\.jar$" \
-log "Downloading Crucible from $downloadUrl"
+  ${crucibleRepo}
-if ! SERVER=$(get --skip-existing --output-filename -o /data "$downloadUrl"); then
+  ); then
-  logError "Crucible jar from $downloadUrl"
+  logError "Failed to download Crucible jar for ${VERSION} from the ${CRUCIBLE_RELEASE} release"
+  logError "Ensure CRUCIBLE_RELEASE is one of the releases at ${crucibleReleasesUrl}"
   exit 1
 fi
 
 librariesDir=/data/libraries
 if [ ! -d "$librariesDir" ]; then
-  if ! librariesUrl=$(get --json-path "$.assets[?(@.name == 'libraries.zip')].browser_download_url" \
+  if ! librariesZip=$(mc-image-helper github download-asset \
-      --accept "application/vnd.github.v3+json" "$crucibleReleaseUrl"); then
+    "${crucibleReleaseArgs[@]}" \
-    logError "Failed to access ${CRUCIBLE_RELEASE} release of Crucible for libraries"
+    --output-directory=/tmp \
+    --name-pattern="^libraries\.zip$" \
+    ${crucibleRepo}
+    ); then
+    logError "Failed to download Crucible libraries from the ${CRUCIBLE_RELEASE} release"
     exit 1
   fi
 
   log "Downloading Crucible libraries"
-  if ! get -o /tmp/libraries.zip "$librariesUrl"; then
+  if ! unzip "$librariesZip" -d "$librariesDir"; then
-    logError "Failed to download Crucible libraries from $librariesUrl"
-    exit 1
-  fi
-
-  if ! unzip /tmp/libraries.zip -d "$librariesDir"; then
     logError "Failed to unzip Crucible libraries"
     exit 1
   fi
-  rm /tmp/libraries.zip
+  rm "$librariesZip"
 fi
 
 export SERVER

scripts/start-deployKetting

@@ -4,12 +4,21 @@
 . "$(dirname "$0")/start-utils"
 isDebugging && set -x
 
-if ! SERVER=$(mc-image-helper github download-latest-asset \
+: "${KETTING_RELEASE:=latest}"
+
+# Only pass --release-tag when a specific release was requested; helper treats
+# omitted as latest
+kettingReleaseArgs=()
+[[ ${KETTING_RELEASE} == latest ]] || kettingReleaseArgs+=(--release-tag="${KETTING_RELEASE}")
+
+if ! SERVER=$(mc-image-helper github download-asset \
+  "${kettingReleaseArgs[@]}" \
   --output-directory=/data \
   --name-pattern="kettinglauncher-.+?(?<!-sources)\.jar" \
   kettingpowered/kettinglauncher
   ); then
-    logError "Failed to download Ketting launcher"
+    logError "Failed to download Ketting launcher release ${KETTING_RELEASE}"
+    logError "Ensure KETTING_RELEASE is one of the releases at https://github.com/kettingpowered/kettinglauncher/releases"
     exit 1
 fi
 

scripts/start-deployNanoLimbo

@@ -4,12 +4,21 @@
 . "$(dirname "$0")/start-utils"
 isDebugging && set -x
 
-if ! SERVER=$(mc-image-helper github download-latest-asset \
+: "${NANOLIMBO_RELEASE:=latest}"
+
+# Only pass --release-tag when a specific release was requested; helper treats
+# omitted as latest
+nanolimboReleaseArgs=()
+[[ ${NANOLIMBO_RELEASE} == latest ]] || nanolimboReleaseArgs+=(--release-tag="${NANOLIMBO_RELEASE}")
+
+if ! SERVER=$(mc-image-helper github download-asset \
+  "${nanolimboReleaseArgs[@]}" \
   --output-directory=/data \
   --name-pattern="NanoLimbo(-.+?(?<!-sources))?\.jar" \
   BoomEaro/NanoLimbo
   ); then
-    logError "Failed to download NanoLimbo"
+    logError "Failed to download NanoLimbo release ${NANOLIMBO_RELEASE}"
+    logError "Ensure NANOLIMBO_RELEASE is one of the releases at https://github.com/BoomEaro/NanoLimbo/releases"
     exit 1
 fi
 

scripts/start-deployPoseidon

@@ -13,21 +13,30 @@ if [ "${VERSION}" != "b1.7.3" ]; then
   exit 1
 fi
 
-# : "${POSEIDON_RELEASE:=latest}" placeholder until I figure out how to add version selection with mc-image-helper
+: "${POSEIDON_RELEASE:=latest}"
 : "${POSEIDON_TYPE:=poseidon}"
 
+# Only pass --release-tag when a specific release was requested; helper treats
+# omitted as latest
+poseidonReleaseArgs=()
+[[ ${POSEIDON_RELEASE} == latest ]] || poseidonReleaseArgs+=(--release-tag="${POSEIDON_RELEASE}")
+
 if [[ ${POSEIDON_TYPE^^} = UBERBUKKIT ]]; then
   poseidonRepo="Moresteck/uberbukkit"
 else
   poseidonRepo="retromcorg/Project-Poseidon"
 fi
 
-if ! SERVER=$(mc-image-helper github download-latest-asset \
+poseidonReleasesUrl=https://github.com/${poseidonRepo}/releases
+
+if ! SERVER=$(mc-image-helper github download-asset \
+  "${poseidonReleaseArgs[@]}" \
   --output-directory=/data \
   --name-pattern="^(?!original-).+\.jar" \
   ${poseidonRepo}
   ); then
-    logError "Failed to download ${POSEIDON_TYPE}"
+    logError "Failed to download ${POSEIDON_TYPE} release ${POSEIDON_RELEASE}"
+    logError "Ensure POSEIDON_RELEASE is one of the releases at ${poseidonReleasesUrl}"
     exit 1
 fi
 

scripts/start-deployPumpkin

@@ -26,20 +26,40 @@ if [[ $(getDistro) == alpine ]]; then
   pumpkinAsset+="-musl"
 fi
 
+pumpkinReleasesUrl=https://github.com/Pumpkin-MC/Pumpkin/releases
+: "${PUMPKIN_RELEASE:=latest}"
+
+# Only pass --release-tag when a specific release was requested; helper treats
+# omitted as latest
+pumpkinReleaseArgs=()
+[[ ${PUMPKIN_RELEASE} == latest ]] || pumpkinReleaseArgs+=(--release-tag="${PUMPKIN_RELEASE}")
+
+# The asset is downloaded to a fixed filename, so discard a previously
+# downloaded executable when a different release is requested
+pumpkinReleaseMarker=/data/.pumpkin-release
+if [[ -f "${pumpkinReleaseMarker}" && $(<"${pumpkinReleaseMarker}") != "${PUMPKIN_RELEASE}" ]]; then
+  log "Switching Pumpkin release from $(<"${pumpkinReleaseMarker}") to ${PUMPKIN_RELEASE}"
+  rm -f "/data/${pumpkinAsset}"
+fi
+
 if isTrue "${FORCE_REDOWNLOAD:-false}"; then
   log "Forcing re-download of ${pumpkinAsset}"
   rm -f "/data/${pumpkinAsset}"
 fi
 
-if ! SERVER=$(mc-image-helper github download-latest-asset \
+if ! SERVER=$(mc-image-helper github download-asset \
+  "${pumpkinReleaseArgs[@]}" \
   --output-directory=/data \
   --name-pattern="^${pumpkinAsset}$" \
   Pumpkin-MC/Pumpkin
   ); then
-    logError "Failed to download ${pumpkinAsset} from the latest Pumpkin release"
+    logError "Failed to download ${pumpkinAsset} from the Pumpkin release ${PUMPKIN_RELEASE}"
+    logError "Ensure PUMPKIN_RELEASE is one of the releases at ${pumpkinReleasesUrl}"
     exit 1
 fi
 
+printf '%s' "${PUMPKIN_RELEASE}" > "${pumpkinReleaseMarker}"
+
 log "Using Pumpkin server executable ${SERVER}"
 if [[ ! -x "${SERVER}" ]]; then
   chmod +x "${SERVER}"

tests/setuponlytests/arclight-release/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "TRUE"
+      SETUP_ONLY: "TRUE"
+      TYPE: ARCLIGHT
+      VERSION: "1.21.1"
+      ARCLIGHT_TYPE: "neoforge"
+      ARCLIGHT_RELEASE: "FeudalKings/1.0.0"
+    volumes:
+      - ./data:/data

tests/setuponlytests/arclight-release/verify.sh

@@ -0,0 +1 @@
+mc-image-helper assert fileExists "/data/arclight-neoforge-1.21.1-1.0.0-3457560.jar"

tests/setuponlytests/crucible-release/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "TRUE"
+      SETUP_ONLY: "TRUE"
+      TYPE: CRUCIBLE
+      VERSION: "1.7.10"
+      CRUCIBLE_RELEASE: "v5.3"
+    volumes:
+      - ./data:/data

tests/setuponlytests/crucible-release/verify.sh

@@ -0,0 +1,6 @@
+mc-image-helper assert fileExists "/data/Crucible-1.7.10-5.3.jar"
+
+if [ ! -d /data/libraries ]; then
+  echo "Expected /data/libraries to have been extracted from libraries.zip"
+  exit 1
+fi

tests/setuponlytests/ketting-release/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "TRUE"
+      SETUP_ONLY: "TRUE"
+      TYPE: KETTING
+      VERSION: "1.20.1"
+      KETTING_RELEASE: "v1.5.1"
+    volumes:
+      - ./data:/data

tests/setuponlytests/ketting-release/verify.sh

@@ -0,0 +1 @@
+mc-image-helper assert fileExists "/data/kettinglauncher-*.jar"

tests/setuponlytests/nanolimbo-release/docker-compose.yml

@@ -0,0 +1,11 @@
+services:
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "TRUE"
+      SETUP_ONLY: "TRUE"
+      TYPE: NANOLIMBO
+      NANOLIMBO_RELEASE: "1.13.0"
+    volumes:
+      - ./data:/data

tests/setuponlytests/nanolimbo-release/verify.sh

@@ -0,0 +1 @@
+mc-image-helper assert fileExists "/data/NanoLimbo*.jar"

tests/setuponlytests/poseidon-release/docker-compose.yml

@@ -0,0 +1,12 @@
+services:
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "TRUE"
+      SETUP_ONLY: "TRUE"
+      TYPE: POSEIDON
+      VERSION: "b1.7.3"
+      POSEIDON_RELEASE: "1.1.12-260720-1033-5303bd5"
+    volumes:
+      - ./data:/data

tests/setuponlytests/poseidon-release/verify.sh

@@ -0,0 +1 @@
+mc-image-helper assert fileExists "/data/poseidon-craftbukkit-*.jar"

tests/setuponlytests/pumpkin-release/docker-compose.yml

@@ -0,0 +1,11 @@
+services:
+  mc:
+    restart: "no"
+    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    environment:
+      EULA: "TRUE"
+      SETUP_ONLY: "TRUE"
+      TYPE: PUMPKIN
+      PUMPKIN_RELEASE: "0.2.0+26.3-26.51"
+    volumes:
+      - ./data:/data

tests/setuponlytests/pumpkin-release/verify.sh

@@ -0,0 +1,7 @@
+mc-image-helper assert fileExists "/data/pumpkin-*-Linux*"
+
+actual=$(<"/data/.pumpkin-release")
+if [[ ${actual} != "0.2.0+26.3-26.51" ]]; then
+  echo "Expected /data/.pumpkin-release to be '0.2.0+26.3-26.51', but was '${actual}'"
+  exit 1
+fi