Corrected stable tag build configuration (#2249)

Also
- removed carry-on from default exclusions

.github/workflows/build-multiarch.yml

@@ -102,6 +102,7 @@ jobs:
     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 != '' }}
+      MAIN_VARIANT: java17
     runs-on: ubuntu-20.04
     steps:
       - name: Checkout
@@ -120,14 +121,20 @@ jobs:
             ${{ github.repository_owner }}/minecraft-server
             ghcr.io/${{ github.repository_owner }}/minecraft-server
           tags: |
-            type=ref,event=tag,enable=${{ matrix.variant == 'java17' }}
+            # For the "main" variant, it gets the tag as-is, without suffix
+            type=ref,event=tag,enable=${{ matrix.variant == env.MAIN_VARIANT }}
+            # and each variant (including main one) gets the tag with the variant suffix, such as 2023.1.1-java17
             type=ref,event=tag,suffix=-${{ matrix.variant }}
+            # latest repo tag gets a moving 'stable' image tag applied to the main variant
+            type=pep440,value=stable,enable=${{ matrix.variant == env.MAIN_VARIANT }},pattern={{version}}
+            # for building test/* branch images
             type=ref,event=branch,suffix=-${{ matrix.variant }},enable=${{ github.ref_name != 'master' }}
+            # 
             type=raw,value=${{ matrix.variant }},enable=${{ github.ref_name == 'master' }}
           # NOTE this identifies which variant will be published as "latest", which isn't
           # necessarily the newest version of Java
           flavor: |
-            latest=${{ matrix.variant == 'java17' && github.ref_name == 'master' }}
+            latest=${{ matrix.variant == env.MAIN_VARIANT && github.ref_name == 'master' }}
           labels: |
             org.opencontainers.image.authors=Geoff Bourne <itzgeoff@gmail.com>
 
@@ -135,10 +142,10 @@ jobs:
         uses: docker/setup-buildx-action@v2
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2.1.0
+        uses: docker/setup-qemu-action@v2.2.0
 
       - name: Build for test
-        uses: docker/build-push-action@v3.3.0
+        uses: docker/build-push-action@v4.1.1
         with:
           platforms: linux/amd64
           tags: ${{ env.IMAGE_TO_TEST }}
@@ -177,7 +184,7 @@ jobs:
           password: ${{ github.token }}
 
       - name: Build and push
-        uses: docker/build-push-action@v3.3.0
+        uses: docker/build-push-action@v4.1.1
         if: github.actor == github.repository_owner
         with:
           platforms: ${{ matrix.platforms }}

.github/workflows/verify-pr.yml

@@ -54,7 +54,7 @@ jobs:
         uses: docker/setup-buildx-action@v2
 
       - name: Confirm multi-arch build
-        uses: docker/build-push-action@v3.3.0
+        uses: docker/build-push-action@v4.1.1
         with:
           platforms: ${{ matrix.platforms }}
           # ensure latest base image is used
@@ -64,7 +64,7 @@ jobs:
           cache-from: type=gha,scope=${{ matrix.variant }}
 
       - name: Build for test
-        uses: docker/build-push-action@v3.3.0
+        uses: docker/build-push-action@v4.1.1
         with:
           # Only build single platform since loading multi-arch image into daemon fails with
           # "docker exporter does not currently support exporting manifest lists"

Dockerfile

@@ -46,7 +46,7 @@ RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
   --var version=0.1.1 --var app=maven-metadata-release --file {{.app}} \
   --from https://github.com/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
 
-ARG MC_HELPER_VERSION=1.29.1
+ARG MC_HELPER_VERSION=1.32.4
 ARG MC_HELPER_BASE_URL=https://github.com/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/server-properties.md

@@ -107,7 +107,7 @@ The server icon which has been set doesn't get overridden by default. It can be
 
 RCON is **enabled by default** to allow for graceful shut down the server and coordination of save state during backups. RCON can be disabled by setting `ENABLE_RCON` to "false".
 
-The default password is "minecraft" but **change the password before deploying into production** by setting `RCON_PASSWORD`.
+The default password is randomly generated if `RCON_PASSWORD` has not been set.
 
 **DO NOT MAP THE RCON PORT EXTERNALLY** unless you aware of all the consequences and have set a **secure password** with `RCON_PASSWORD`. 
 
@@ -321,18 +321,17 @@ If you must, the server port can be set like:
 
 | Environment Variable              | Server Property                   |
 | --------------------------------- | --------------------------------- |
-| PLAYER_IDLE_TIMEOUT               | player-idle-timeout               |
 | BROADCAST_CONSOLE_TO_OPS          | broadcast-console-to-ops          |
 | BROADCAST_RCON_TO_OPS             | broadcast-rcon-to-ops             |
-| ENABLE_JMX                        | enable-jmx-monitoring             |
-| SYNC_CHUNK_WRITES                 | sync-chunk-writes                 |
 | ENABLE_STATUS                     | enable-status                     |
+| ENFORCE_SECURE_PROFILE            | enforce-secure-profile            |
 | ENTITY_BROADCAST_RANGE_PERCENTAGE | entity-broadcast-range-percentage |
 | FUNCTION_PERMISSION_LEVEL         | function-permission-level         |
 | NETWORK_COMPRESSION_THRESHOLD     | network-compression-threshold     |
 | OP_PERMISSION_LEVEL               | op-permission-level               |
+| PLAYER_IDLE_TIMEOUT               | player-idle-timeout               |
 | PREVENT_PROXY_CONNECTIONS         | prevent-proxy-connections         |
-| USE_NATIVE_TRANSPORT              | use-native-transport              |
-| ENFORCE_WHITELIST                 | enforce-whitelist                 |
-| ENABLE_WHITELIST                  | white-list and whitelist          |
 | SIMULATION_DISTANCE               | simulation-distance               |
+| SYNC_CHUNK_WRITES                 | sync-chunk-writes                 |
+| USE_NATIVE_TRANSPORT              | use-native-transport              |
+

docs/index.md

@@ -1,6 +1,5 @@
----
-title: Intro
----
+# Intro
+
 [![Docker Pulls](https://img.shields.io/docker/pulls/itzg/minecraft-server.svg)](https://hub.docker.com/r/itzg/minecraft-server/)
 [![Docker Stars](https://img.shields.io/docker/stars/itzg/minecraft-server.svg?maxAge=2592000)](https://hub.docker.com/r/itzg/minecraft-server/)
 [![GitHub Issues](https://img.shields.io/github/issues-raw/itzg/docker-minecraft-server.svg)](https://github.com/itzg/docker-minecraft-server/issues)
@@ -30,4 +29,38 @@ where, in this case, the standard server port 25565, will be exposed on your hos
 
     **DO NOT** port forward RCON on 25575 without first setting `RCON_PASSWORD` to a secure value. It is highly recommended to only use RCON within the container, such as with `rcon-cli`. 
 
-By default, the container will download the latest version of the "vanilla" [Minecraft: Java Edition server](https://www.minecraft.net/en-us/download/server) provided by Mojang. The [`VERSION`](versions/java.md) and the [`TYPE`](server-types/bukkit-spigot.md) can be configured to create many variations of desired Minecraft server. 
+By default, the container will download the latest version of the "vanilla" [Minecraft: Java Edition server](https://www.minecraft.net/en-us/download/server) provided by Mojang. The [`VERSION`](versions/java.md) and the [`TYPE`](types-and-platforms/index.md) can be configured to create many variations of desired Minecraft server. 
+
+## Using [Docker Compose](https://docs.docker.com/compose/)
+
+1. Create a new directory
+2. Put the contents of the file below in a file called `docker-compose.yml`
+3. Run `docker compose up -d` in that directory
+4. Done! Point your client at your host's name/IP address and port 25565.
+
+```yaml
+version: "3.8"
+
+services:
+  mc:
+    image: itzg/minecraft-server
+    tty: true
+    stdin_open: true
+    ports:
+      - "25565:25565"
+    environment:
+      EULA: "TRUE"
+    volumes:
+      # attach the relative directory 'data' to the container's /data path
+      - ./data:/data
+```
+
+To apply changes made to the compose file, just run `docker compose up -d` again.
+
+Follow the logs of the container using `docker compose logs -f`, check on the status with `docker compose ps`, and stop the container using `docker compose stop`.
+
+!!! note "More Compose Examples"
+    There are more [examples located in the Github repo](https://github.com/itzg/docker-minecraft-server/tree/master/examples).
+
+!!! note "Deployment Examples"
+    The [deployments page](misc/deployment/index.md) provides more examples of deployment with and beyond Docker Compose.

docs/misc/autopause-autostop/autopause.md

@@ -1,20 +1,14 @@
-# AutoPause
+# Auto-Pause
 
-### Description
+An auto-pause functionality is provided that monitors whether clients are connected to the server. If a client is not connected for a specified time, the Java process is put into a pause state. When a client attempts to connect while the process is paused, then process will be restored to a running state. The experience for the client does not change. This feature can be enabled by setting the environment variable `ENABLE_AUTOPAUSE` to "true".
 
-There are various bug reports on [Mojang](https://bugs.mojang.com) about high CPU usage of servers with newer versions, even with few or no clients connected (e.g. [this one](https://bugs.mojang.com/browse/MC-149018), in fact the functionality is based on [this comment in the thread](https://bugs.mojang.com/browse/MC-149018?focusedCommentId=593606&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-593606)).
+!!! important
 
-An autopause functionality has been added to this image to monitor whether clients are connected to the server. If for a specified time no client is connected, the Java process is stopped. When knocking on the server port (e.g. by the ingame Multiplayer server overview), the process is resumed. The experience for the client does not change.
-
-Of course, even loaded chunks are not ticked when the process is stopped.
-
-**You must greatly increase or disable max-tick-time watchdog functionality.** From the server's point of view, the pausing causes a single tick to take as long as the process is stopped, so the server watchdog might intervene after the process is continued, possibly forcing a container restart. To prevent this, ensure that the `max-tick-time` in the `server.properties` file is set to a very large value or -1 to disable it entirely, which is highly recommended. That can be set with `MAX_TICK_TIME` as described in [the section below](../../configuration/server-properties.md#max-tick-time).
-
-!!! note 
+    **You must greatly increase or disable max-tick-time watchdog functionality.** From the server's point of view, the pausing causes a single tick to take as long as the process is stopped, so the server watchdog might intervene after the process is continued, possibly forcing a container restart. To prevent this, ensure that the `max-tick-time` in the `server.properties` file is set to a very large value or -1 to disable it entirely, which is highly recommended. That can be set with `MAX_TICK_TIME` as described in [the section below](../../configuration/server-properties.md#max-tick-time).
 
     Non-vanilla versions might have their own configuration file, you might have to disable their watchdogs separately. For PaperMC servers, you need to send the JVM flag `-Ddisable.watchdog=true`, this can be done with the docker env variable `-e JVM_DD_OPTS=disable.watchdog:true`
 
-On startup the `server.properties` file is checked and, if applicable, a warning is printed to the terminal. When the server is created (no data available in the persistent directory), the properties file is created with the Watchdog disabled.
+    On startup the `server.properties` file is checked and, if applicable, a warning is printed to the terminal. When the server is created (no data available in the persistent directory), the properties file is created with the Watchdog disabled.
 
 The utility used to wake the server (`knock(d)`) works at network interface level. So the correct interface has to be set using the `AUTOPAUSE_KNOCK_INTERFACE` variable when using non-default networking environments (e.g. host-networking, Portainer oder NAS solutions). See the description of the variable below.
 
@@ -22,20 +16,14 @@ A file called `.paused` is created in `/data` directory when the server is pause
 
 A starting, example compose file has been provided in [examples/docker-compose-autopause.yml](https://github.com/itzg/docker-minecraft-server/blob/master/examples/docker-compose-autopause.yml).
 
-### Enabling Autopause
-
-Enable the Autopause functionality by setting:
-
-```
--e ENABLE_AUTOPAUSE=TRUE
-```
-
-Autopause is not compatible with `EXEC_DIRECTLY=true` and the two cannot be set together.
+Auto-pause is not compatible with `EXEC_DIRECTLY=true` and the two cannot be set together.
 
 !!! note 
 
     When configuring kubernetes readiness/liveness health checks with auto-pause enabled, be sure to reference the `mc-health` wrapper script rather than `mc-status` directly.
 
+## Additional configuration
+
 The following environment variables define the behaviour of auto-pausing:
 
 - `AUTOPAUSE_TIMEOUT_EST`, default `3600` (seconds)
@@ -53,7 +41,7 @@ The following environment variables define the behaviour of auto-pausing:
 
     To troubleshoot, add `DEBUG_AUTOPAUSE=true` to see additional output
 
-### Rootless Autopause
+## Rootless Auto-Pause
 
 If you're running the container as rootless, you might need to set change the default port forwarder from RootlessKit to slirp4netns.
 

docs/misc/autopause-autostop/autostop.md

@@ -1,4 +1,4 @@
-# AutoStop
+# Auto-Stop
 
 An option to stop the server after a specified time has been added for niche applications (e.g. billing saving on AWS Fargate). The function is incompatible with the Autopause functionality, as they basically cancel out each other.
 

docs/misc/contributing/building.md

@@ -1,11 +1,28 @@
-Ensure buildx/BuildKit support is enabled and run:
 
-```shell script
-docker buildx build --platform=linux/arm64 --platform=linux/arm/v7 --platform=linux/amd64 --tag itzg/minecraft-server:multiarch --push .
+## Building image locally with alternate Java base
+
+The following shows how to change the base Java image used by the build:
+
+```shell
+docker build --build-arg BASE_IMAGE=ghcr.io/graalvm/graalvm-ce:ol8-java11 -t IMG_PREFIX/minecraft-server:java11-graalvm .
 ```
 
-To build for local testing, use:
+## Building a multi-architecture image
 
-```shell script
-docker buildx build --platform=linux/amd64 --tag mc-multiarch --load .
+Ensure buildx/BuildKit support is enabled and run the following to build multi-architecture and push to the repository as named by the image:
+
+```shell
+docker buildx build --platform=linux/arm64 --platform=linux/arm/v7 --platform=linux/amd64 --tag IMG_PREFIX/minecraft-server --push .
+```
+
+To build for local images, multi-architecture is not supported, use the following with buildx to load the image into the local daemon:
+
+```shell
+docker buildx build --tag IMG_PREFIX/minecraft-server --load .
+```
+
+or just a plain build
+
+```shell
+docker build -t IMG_PREFIX/minecraft-server .
 ```

docs/misc/contributing/development.md

@@ -55,14 +55,14 @@ docker run -it --rm -v ${PWD}:/scripts -e SCRIPTS=/scripts/ --entrypoint bash mc
 From within the container you can run individual scripts via the attached `/scripts/` path; however, be sure to set any environment variables expected by the scripts by either `export`ing them manually:
 
 ```shell script
-export VANILLA_VERSION=1.12.2
+export VERSION=1.12.2
 /scripts/start-magma
 ```
 
 ...or pre-pending script execution:
 
 ```shell script
-VANILLA_VERSION=1.12.2 /scripts/start-magma
+VERSION=1.12.2 /scripts/start-magma
 ```
 
 > NOTE: You may want to temporarily add an `exit` statement near the end of your script to isolate execution to just the script you're developing.
@@ -75,17 +75,19 @@ In the cloned copy of [`mc-image-helper`](https://github.com/itzg/mc-image-helpe
 ./gradlew distTar
 ```
 
-Assuming [http-server](https://www.npmjs.com/package/http-server) is installed globally, start a static web server using:
+!!! note
+    The distribution's version will be `0.0.0-<branch>-SNAPSHOT`
+
+Assuming Java 18 or newer:
 
 ```shell
-http-server ./build/distributions -p 8080
+cd build/distributions
+jwebserver -b 0.0.0.0 -p 8008
 ```
 
-Note the port that was selected by http-server and pass the build arguments, such as:
-
 ```shell
 --build-arg MC_HELPER_VERSION=1.8.1-SNAPSHOT \
---build-arg MC_HELPER_BASE_URL=http://host.docker.internal:8080
+--build-arg MC_HELPER_BASE_URL=http://host.docker.internal:8008
 ```
 
 Now the image can be built like normal, and it will install mc-image-helper from the locally built copy.

docs/misc/deployment/aws.md

@@ -1 +0,0 @@
-If you're looking for a simple way to deploy this to the Amazon Web Services Cloud, check out the [Minecraft Server Deployment (CloudFormation) repository](https://github.com/vatertime/minecraft-spot-pricing). This repository contains a CloudFormation template that will get you up and running in AWS in a matter of minutes. Optionally it uses Spot Pricing so the server is very cheap, and you can easily turn it off when not in use.

docs/misc/deployment/docker-compose.md

@@ -1,26 +0,0 @@
-Rather than type the server options below, the port mappings above, etc
-every time you want to create new Minecraft server, you can now use
-[Docker Compose](https://docs.docker.com/compose/). Start with a
-`docker-compose.yml` file like the following:
-
-``` yaml
-version: "3"
-
-services:
-  mc:
-    image: itzg/minecraft-server
-    ports:
-      - 25565:25565
-    environment:
-      EULA: "TRUE"
-    tty: true
-    stdin_open: true
-    restart: unless-stopped
-```
-
-and in the same directory as that file run
-
-    docker-compose up -d
-
-Now, go play...or adjust the `environment` section to configure
-this server instance.

docs/misc/deployment/helmcharts.md

@@ -1,8 +0,0 @@
-- itzg Helm Chart:
-    - [GitHub repo](https://github.com/itzg/minecraft-server-charts)
-    - [Helm Chart repo](https://itzg.github.io/minecraft-server-charts/)
-- [mcsh/server-deployment](https://github.com/mcserverhosting-net/charts)
-
-### Examples
-
-The [examples directory](https://github.com/itzg/docker-minecraft-server/tree/master/examples) also provides examples of deploying the [itzg/minecraft-server](https://hub.docker.com/r/itzg/minecraft-server/) Docker image.

docs/misc/deployment/index.md

@@ -0,0 +1,22 @@
+# More Deployment Info 
+
+## Using Helm
+
+- itzg Helm Chart:
+    - [GitHub repo](https://github.com/itzg/minecraft-server-charts)
+      - [Helm Chart repo](https://itzg.github.io/minecraft-server-charts/)
+- [mcsh/server-deployment](https://github.com/mcserverhosting-net/charts)
+
+## Supporting Articles
+
+Below are supporting articles for server deployment.
+
+- "Zero to Minecraft Server with Docker Desktop and Compose"
+
+    https://dev.to/rela-v/zero-to-minecraft-server-with-docker-desktop-and-compose-500a
+
+    - This is a reference guide/tutorial on how to set up a vanilla Minecraft server using this project, including step-by-step instructions, and information on topics such as port-forwarding.
+
+## Deploying onto AWS
+
+If you're looking for a simple way to deploy this to the Amazon Web Services Cloud, check out the [Minecraft Server Deployment (CloudFormation) repository](https://github.com/vatertime/minecraft-spot-pricing). This repository contains a CloudFormation template that will get you up and running in AWS in a matter of minutes. Optionally it uses Spot Pricing so the server is very cheap, and you can easily turn it off when not in use.

docs/mods-and-plugins/forge-api.md

@@ -0,0 +1,65 @@
+# Forge API
+
+## ForgeAPI usage to use non-version specific projects
+
+!!! warning "Deprecated"
+    This approach will soon be deprecated in favor of a variation of `AUTO_CURSEFORGE`.
+
+!!! warning
+    This potentially could lead to unexpected behavior if the Mod receives an update with unexpected behavior.
+
+This is more complicated because you will be pulling/using the latest mod for the release of your game. To get started make sure you have a [CursedForge API Key](https://docs.curseforge.com/#getting-started). Then use the environmental parameters in your docker build.
+
+Please be aware of the following when using these options for your mods:
+* Mod Release types: Release, Beta, and Alpha.
+* Mod dependencies: Required and Optional
+* Mod family: Fabric, Forge, and Bukkit.
+
+Parameters to use the ForgeAPI:
+
+* `MODS_FORGEAPI_KEY` - Required
+* `MODS_FORGEAPI_FILE` - Required or use MODS_FORGEAPI_PROJECTIDS (Overrides MODS_FORGEAPI_PROJECTIDS)
+* `MODS_FORGEAPI_PROJECTIDS` - Required or use MODS_FORGEAPI_FILE
+* `MODS_FORGEAPI_RELEASES` - Default is release, Options: [Release|Beta|Alpha]
+* `MODS_FORGEAPI_DOWNLOAD_DEPENDENCIES` - Default is False, attempts to download required mods (releaseType Release) defined in Forge.
+* `MODS_FORGEAPI_IGNORE_GAMETYPE` - Default is False, Allows for filtering mods on family type: FORGE, FABRIC, and BUKKIT. (Does not filter for Vanilla or custom)
+* `REMOVE_OLD_FORGEAPI_MODS` - Default is False
+* `REMOVE_OLD_DATAPACKS_DEPTH` - Default is 1
+* `REMOVE_OLD_DATAPACKS_INCLUDE` - Default is *.jar
+
+Example of expected forge api project ids, releases, and key:
+
+```yaml
+  MODS_FORGEAPI_PROJECTIDS: 306612,256717
+  MODS_FORGEAPI_RELEASES: Release
+  MODS_FORGEAPI_KEY: $WRX...
+```
+
+Example of expected ForgeAPI file format.
+
+**Field Description**:
+* `name` is currently unused, but can be used to document each entry.
+* `projectId` id is the id found on the CurseForge website for a particular mod
+* `releaseType` Type corresponds to forge's R, B, A icon for each file. Default Release, options are (release|beta|alpha).
+* `fileName` is used for version pinning if latest file will not work for you.
+
+```json
+[
+  {
+      "name": "fabric api",
+      "projectId": "306612",
+      "releaseType": "release"
+  },
+  {
+      "name": "fabric voice mod",
+      "projectId": "416089",
+      "releaseType": "beta"
+  },
+  {
+      "name": "Biomes o plenty",
+      "projectId": "220318",
+      "fileName": "BiomesOPlenty-1.18.1-15.0.0.100-universal.jar",
+      "releaseType": "release"
+  }
+]
+```

docs/mods-and-plugins/index.md

@@ -1,15 +1,35 @@
+# Working with mods and plugins
+
+## Mod platforms
+
+By far the easiest way to work with mod and plugins, especially large numbers of them, is to utilize modpacks with [one of the supported mod platforms](../types-and-platforms/index.md).
+
+The following are some supported mod platforms:
+
+- [Modrinth](../types-and-platforms/mod-platforms/modrinth-modpacks.md) 
+- [CurseForge](../types-and-platforms/mod-platforms/auto-curseforge.md)
+- [Feed the Beast](../types-and-platforms/mod-platforms/ftb.md)
+
+## Download automation
+
+On the left, there are sections describing some download automation options.
+
+## Mods vs Plugins
+
+The terms "mods" and "plugins" can be quite confusing. Generally, the rule of thumb is that "mods" are used by the types that run client side to modify rendering, add new blocks, and add behaviors server, such as [Forge](../types-and-platforms/server-types/forge.md) and [Fabric](../types-and-platforms/server-types/fabric.md). "Plugins" are used by the types that **only run on servers** to add behaviors, commands, etc such as [Paper](../types-and-platforms/server-types/paper.md) (which derives from [Bukkit/Spigot](../types-and-platforms/server-types/bukkit-spigot.md)). There are also some types that are [hybrids](../types-and-platforms/server-types/hybrids.md), such as Magma, that use both "mods" and "plugins"
+
 ## Optional plugins, mods, and config attach points
 
 There are optional volume paths that can be attached to supply content to be copied into the data area:
 
 `/plugins`
-: contents are synchronized into `/data/plugins` for Bukkit related server types. The source can be changed by setting `COPY_PLUGINS_SRC`. The destination can be changed by setting `COPY_PLUGINS_DEST`. Set `SYNC_SKIP_NEWER_IN_DESTINATION=false` if you want files from `/plugins` to take precedence over newer files in `/data/plugins`.
+: content in this directory is synchronized into `/data/plugins` for server types that use plugins, [as described above](#mods-vs-plugins). For special cases, the source can be changed by setting `COPY_PLUGINS_SRC` and destination by setting `COPY_PLUGINS_DEST`.
 
 `/mods`
-: contents are synchronized into `/data/mods` for Fabric and Forge related server types. The source can be changed by setting `COPY_MODS_SRC`. The destination can be changed by setting `COPY_MODS_DEST`.
+: content in this directory is synchronized into `/data/mods` for server types that use mods, [as described above](#mods-vs-plugins). For special cases, the source can be changed by setting `COPY_MODS_SRC` and destination by setting `COPY_MODS_DEST`.
 
 `/config`
-: contents are synchronized into `/data/config` by default, but can be changed with `COPY_CONFIG_DEST`. The source can be changed by setting `COPY_CONFIG_SRC`. For example, `-v ./config:/config -e COPY_CONFIG_DEST=/data` will allow you to copy over files like `bukkit.yml` and so on directly into the server directory. Set `SYNC_SKIP_NEWER_IN_DESTINATION=false` if you want files from `/config` to take precedence over newer files in `/data/config`.
+: contents are synchronized into `/data/config` by default, but can be changed with `COPY_CONFIG_DEST`. For example, `-v ./config:/config -e COPY_CONFIG_DEST=/data` will allow you to copy over files like `bukkit.yml` and so on directly into the server directory. The source can be changed by setting `COPY_CONFIG_SRC`. Set `SYNC_SKIP_NEWER_IN_DESTINATION=false` if you want files from `/config` to take precedence over newer files in `/data/config`.
 
 By default, the [environment variable processing](../configuration/interpolating.md) is performed on synchronized files that match the expected suffixes in `REPLACE_ENV_SUFFIXES` (by default "yml,yaml,txt,cfg,conf,properties,hjson,json,tml,toml") and are not excluded by `REPLACE_ENV_VARIABLES_EXCLUDES` and `REPLACE_ENV_VARIABLES_EXCLUDE_PATHS`. This processing can be disabled by setting `REPLACE_ENV_DURING_SYNC` to `false`.
 
@@ -21,43 +41,9 @@ For example: `-e REMOVE_OLD_MODS=TRUE -e REMOVE_OLD_MODS_INCLUDE="*.jar" -e REMO
 
 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.
 
-> For more flexibility with mods/plugins preparation, you can declare directories to use in [the `MODS` variable](#zip-file-modpack)
+!!! information ""
+    For more flexibility with mods/plugins preparation, you can declare other directories, files, and URLs to use in [the `MODS` / `PLUGINS` variables](#modsplugins-list).
 
-## Auto-downloading SpigotMC/Bukkit/PaperMC plugins with Spiget
-
-The `SPIGET_RESOURCES` variable can be set with a comma-separated list of SpigotMC resource IDs to automatically download [SpigotMC resources/plugins](https://www.spigotmc.org/resources/) using [the spiget API](https://spiget.org/). Resources that are zip files will be expanded into the plugins directory and resources that are simply jar files will be moved there.
-
-> NOTE: the variable is purposely spelled SPIG**E**T with an "E"
-
-The **resource ID** can be located from the numerical part of the URL after the shortname/slug and a dot. For example, the ID is **28140** from
-
-    https://www.spigotmc.org/resources/luckperms.28140/
-                                                 =====
-
-For example, the following will auto-download the [LuckPerms](https://www.spigotmc.org/resources/luckperms.28140/) and [Vault](https://www.spigotmc.org/resources/vault.34315/) plugins:
-
-    -e SPIGET_RESOURCES=28140,34315
-
-!!! note
-    Some plugins, such as EssentialsX (resource ID 9089), do not permit automated downloads via Spiget. Instead you will need to pre-download the desired file and supply it to the container, such as using the `/plugins` mount point, described above.
-
-## Auto-download mods and plugins from Modrinth
-
-[Modrinth](https://modrinth.com/) is an open source modding platform with a clean, easy to use website for finding [Fabric and Forge mods](https://modrinth.com/mods). At startup, the container will automatically locate and download the newest versions of mod/plugin files that correspond to the `TYPE` and `VERSION` in use. Older file versions downloaded previously will automatically be cleaned up.
-
-- **MODRINTH_PROJECTS** : comma separated list of project slugs (short name) or IDs. The project ID can be located in the "Technical information" section. The slug is the part of the page URL that follows `/mod/`:
-  ```
-    https://modrinth.com/mod/fabric-api
-                             ----------
-                              |
-                              +-- project slug
-  ```
-  Also, specific version/type can be declared using colon symbol and version id/type after the project slug. The version id can be found at 'Metadata' section. Valid version types are `release`, `beta`, `alpha`. For instance:
-  ```
-    -e MODRINTH_PROJECTS=fabric-api,fabric-api:PbVeub96,fabric-api:beta
-  ```
-- **MODRINTH_DOWNLOAD_OPTIONAL_DEPENDENCIES**=true : required dependencies of the project will _always_ be downloaded and optional dependencies can also be downloaded by setting this to `true`
-- **MODRINTH_ALLOWED_VERSION_TYPE**=release : the version type is used to determine the newest version to use from each project. The allowed values are `release`, `beta`, `alpha`.
 
 ## Zip file modpack
 
@@ -74,15 +60,6 @@ docker run -d -e MODPACK=http://www.example.com/mods/modpack.zip ...
     top level of the zip archive. Make sure the jars are compatible with the
     particular `TYPE` of server you are running.
 
-You may also download or copy over individual mods using the `MODS` environment variable. `MODS` contains a comma-separated list of
-- URL of a jar file
-- container path to a jar file
-- container path to a directory containing jar files
-
-```shell
-docker run -d -e MODS=https://www.example.com/mods/mod1.jar,/plugins/common,/plugins/special/mod2.jar ...
-```
-
 ## Generic pack files
 
 To install all the server content (jars, mods, plugins, configs, etc.) from a zip or tgz file, then set `GENERIC_PACK` to the container path or URL of the archive file. This can also be used to apply a CurseForge modpack that is missing a server start script and/or Forge installer.
@@ -103,9 +80,27 @@ If applying large generic packs, the update can be time-consuming. To skip the u
 
 The most time-consuming portion of the generic pack update is generating and comparing the SHA1 checksum. To skip the checksum generation, set `SKIP_GENERIC_PACK_CHECKSUM` to "true.
 
+## 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
+- URL of a jar file
+- container path to a jar file
+- container path to a directory containing jar files
+
+```shell
+docker run -d -e MODS=https://www.example.com/mods/mod1.jar,/plugins/common,/plugins/special/mod2.jar ...
+```
+
+The newline delimiting allows for compose file usage like:
+```yaml
+      PLUGINS: |
+        https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot
+        https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/spigot
+```
+
 ## Mod/Plugin URL Listing File 
 
-As an alternative to `MODS`, the variable `MODS_FILE` can be set with the path to a text file listing a mod/plugin URL on each line. For example, the following
+As an alternative to `MODS`/`PLUGINS`, the variable `MODS_FILE` or `PLUGINS_FILE` can be set with the container path or URL of a text file listing a mod/plugin URLs on each line. For example, the following
 
      -e MODS_FILE=/extras/mods.txt
 
@@ -126,8 +121,6 @@ https://edge.forgecdn.net/files/2871/647/ToastControl-1.15.2-3.0.1.jar
 
     [This compose file](https://github.com/itzg/docker-minecraft-server/blob/master/examples/docker-compose-mods-file.yml) shows another example of using this feature.
 
-    It is recommended to combine this option with `REMOVE_OLD_MODS=TRUE` to ensure the mods/plugins remain consistent with the file's listing.
-
 ## Remove old mods/plugins
 
 When the `MODPACK` option above is specified you can also instruct script to delete old mods/plugins prior to installing new ones. This behaviour is desirable in case you want to upgrade mods/plugins from downloaded zip file.

docs/mods-and-plugins/modrinth.md

@@ -0,0 +1,18 @@
+# Auto-download from Modrinth
+
+[Modrinth](https://modrinth.com/) is an open source modding platform with a clean, easy to use website for finding [Fabric and Forge mods](https://modrinth.com/mods). At startup, the container will automatically locate and download the newest versions of mod/plugin files that correspond to the `TYPE` and `VERSION` in use. Older file versions downloaded previously will automatically be cleaned up.
+
+- **MODRINTH_PROJECTS** : comma separated list of project slugs (short name) or IDs. The project ID can be located in the "Technical information" section. The slug is the part of the page URL that follows `/mod/`:
+  ```
+    https://modrinth.com/mod/fabric-api
+                             ----------
+                              |
+                              +-- project slug
+  ```
+  Also, specific version/type can be declared using colon symbol and version id/type after the project slug. The version id can be found at 'Metadata' section. Valid version types are `release`, `beta`, `alpha`. For instance:
+  ```
+    -e MODRINTH_PROJECTS=fabric-api,fabric-api:PbVeub96,fabric-api:beta
+  ```
+- **MODRINTH_DOWNLOAD_OPTIONAL_DEPENDENCIES**=true : required dependencies of the project will _always_ be downloaded and optional dependencies can also be downloaded by setting this to `true`
+- **MODRINTH_ALLOWED_VERSION_TYPE**=release : the version type is used to determine the newest version to use from each project. The allowed values are `release`, `beta`, `alpha`.
+

docs/mods-and-plugins/spiget.md

@@ -0,0 +1,19 @@
+# Auto-download using Spiget
+
+The `SPIGET_RESOURCES` variable can be set with a comma-separated list of SpigotMC resource IDs to automatically download [Spigot/Bukkit/Paper plugins](https://www.spigotmc.org/resources/) using [the spiget API](https://spiget.org/). Resources that are zip files will be expanded into the plugins directory and resources that are simply jar files will be moved there.
+
+!!! important "SPIGET not SPIGOT"
+    The variable is purposely spelled SPIG**E**T with an "E"
+
+The **resource ID** can be located from the numerical part of the URL after the shortname/slug and a dot. For example, the ID is **28140** from
+
+    https://www.spigotmc.org/resources/luckperms.28140/
+                                                 =====
+
+For example, the following will auto-download the [LuckPerms](https://www.spigotmc.org/resources/luckperms.28140/) and [Vault](https://www.spigotmc.org/resources/vault.34315/) plugins:
+
+    -e SPIGET_RESOURCES=28140,34315
+
+!!! note
+    Some plugins, such as EssentialsX (resource ID 9089), do not permit automated downloads via Spiget. Instead, you will need to pre-download the desired file and supply it to the container, such as using the `/plugins` mount point, described [in the main section](index.md).
+

docs/types-and-platforms/index.md

@@ -0,0 +1,14 @@
+# Server Types and Mod Platforms
+
+Server types can be selected by setting the `TYPE` environment variable to one of the types described in these sections.
+
+The default server type is [the official software provided by Mojang](https://www.minecraft.net/en-us/download/server), which can be explicitly selected by setting `TYPE` to "VANILLA".
+
+**From the sections to the left...**
+
+The **mod platforms** take a modpack identifier, file, etc and use that to select and download the appropriate version of a mod loader, such as Forge or Fabric, downloading declared mods/plugins, and apply any additional files. The mod platforms are selected by setting `MOD_PLATFORM`; however, for ease of use and compatibility, the selection can be set in `TYPE`.
+
+The individual **server types** allow for selecting the mod loader / server type and specific versions of those. 
+
+!!! important
+    For all the server types, the `VERSION` environment variable is used to declare the Minecraft version itself, such as 1.19.4. Each server type will have specific variables for qualifying their version in addition to the Minecraft version.

docs/types-and-platforms/mod-platforms/auto-curseforge.md

@@ -1,220 +1,111 @@
-## Auto CurseForge Management
-
-To manage a CurseForge modpack automatically with upgrade support, pinned or latest version tracking, set `TYPE` to "AUTO_CURSEFORGE". The appropriate mod loader (Forge / Fabric) version will be automatically installed as declared by the modpack. This mode will also take care of cleaning up unused files installed by previous versions of the modpack, but world data is never auto-removed.
-
-### API Key
-
-!!! warning "CurseForge API key usage"
-
-    A CurseForge API key is **required** to use this feature. Go to their [developer console](https://console.curseforge.com/), generate an API key, and set the environment variable `CF_API_KEY`.
-    
-    When entering your API Key in a docker compose file you will need to escape any `$` character with a second `$`.
-    
-    Example if your key is `$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa`:
-    ```yaml
-    environment:
-      CF_API_KEY: '$$11$$22$$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
-    ```
-    If you use `docker run` you will need to make sure to use single quotes:
-    
-    ```shell
-    docker run ... -e CF_API_KEY='$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
-    ```
-    
-    To avoid exposing the API key, it is highly recommended to use a `.env` file, which is [loaded automatically by docker compose](https://docs.docker.com/compose/environment-variables/set-environment-variables/#substitute-with-an-env-file). `$`'s in the value still need to escaped with a second `$` and the variable needs to be referenced from the compose file, such as:
-    ```yaml
-    environment:
-      CF_API_KEY: ${CF_API_KEY}
-    ```
-    
-    To use the equivalent with `docker run` you need to specify the `.env` file explicitly:
-    ```
-    docker run --env-file=.env itzg/minecraft-server
-    ```
-
-!!! note
-
-    Be sure to use the appropriate [image tag for the Java version compatible with the modpack](../versions/java.md).
-    
-    Most modpacks require a good amount of memory, so it best to set `MEMORY` to at least "4G" since the default is only 1 GB.
-
-### Usage
-
-Use one of the following to specify the modpack to install:
-
-Pass a page URL to the modpack or a specific file with `CF_PAGE_URL` such as the modpack page "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8" or a specific file "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390". For example:
-
-```
--e TYPE=AUTO_CURSEFORGE -e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8
-```
-
-Instead of a URL, the modpack slug can be provided as `CF_SLUG`. The slug is the short identifier visible in the URL after "/modpacks/", such as
-
-![cf-slug](../img/cf-slug.png)
-
-For example:
-```
--e TYPE=AUTO_CURSEFORGE -e CF_SLUG=all-the-mods-8
-```
-
-For mod, modpacks, and world files that are not allowed for automated download, the container path `/downloads` can be attached and matching files will be retrieved from there. The subdirectories `mods`, `modpacks`, and `worlds` will also be checked accordingly. To change the source location of downloaded files, set `CF_DOWNLOADS_REPO` to an existing container path. To disable this feature, set `CF_DOWNLOADS_REPO` to an empty string.
-
-If the authors of the modpack have disallowed project distribution, then the desired **client** modpack zip will need to be manually downloaded and made available to the container. The path to that file must be passed to `CF_MODPACK_ZIP`. Similarly, the container path to a modpack manifest JSON can be passed to `CF_MODPACK_MANIFEST`.  In either case, the modpack slug or page URL must still be provided.
-
-The latest file will be located and used by default, but if a specific version is desired you can use one of the following options. With any of these options **do not select a server file** -- they lack the required manifest and defeat the ability to consistently automate startup.
-
-- Use `CF_PAGE_URL`, but include the full URL to a specific file
-- Set `CF_FILE_ID` to the numerical file ID
-- Specify a substring to match the desired filename with `CF_FILENAME_MATCHER`
-
-The following shows where to get the URL to the specific file and also shows where the file ID is located:
-
-![cf-file-id](../img/cf-file-id.png)
-
-The following examples all refer to version 1.0.7 of ATM8:
-
-```
--e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390
-```
-
-```
--e CF_SLUG=all-the-mods-8 -e CF_FILE_ID=4248390
-```
-
-```
--e CF_SLUG=all-the-mods-8 -e CF_FILENAME_MATCHER=1.0.7
-```
-
-### Exlude client mods
-
-Quite often there are mods that need to be excluded, such as ones that did not properly declare as a client mod via the file's game versions. Similarly, there are some mods that are incorrectly tagged as client only. The following describes two options to exclude/include mods:
-
-Mods can be excluded by passing a comma or space delimited list of **project** slugs or IDs via `CF_EXCLUDE_MODS`. Similarly, there are some mods that are incorrectly tagged as client only. For those, pass the **project** slugs or IDs via `CF_FORCE_INCLUDE_MODS`. These lists will be combined with the content of the exclude/include file, if given.
-
-A mod's project ID can be obtained from the right hand side of the project page:
-![cf-project-id](../img/cf-project-id.png)
-
-For more complex scenarios, global and per modpack exclusions can be declared in a container-accessible JSON file and referenced with `CF_EXCLUDE_INCLUDE_FILE`. By default, [the file bundled with the image](https://raw.githubusercontent.com/itzg/docker-minecraft-server/master/files/cf-exclude-include.json) will be used, but can be disabled by setting this to an empty string. The schema of this file [is documented here](https://github.com/itzg/mc-image-helper#excludeinclude-file-schema).
-
-If needing to iterate on the options above, set `CF_FORCE_SYNCHRONIZE` to "true" to ensure the exclude/includes are re-evaluated.
-
-!!! important
-    These options are provided to empower you to get your server up and running quickly. Please help out by reporting an issue with the respective mod project. Ideally mod developers should [use correct registrations for one-sided client mods](https://docs.minecraftforge.net/en/latest/concepts/sides/#writing-one-sided-mods). Understandably, those code changes may be non-trivial, so mod authors can also add "Client" to the game versions when publishing.
-
-### Extra options
-
-Some modpacks come with world/save data via a worlds file and/or the overrides provided with the modpack. Either approach can be selected to set the `LEVEL` to the resulting saves directory by setting `CF_SET_LEVEL_FROM` to either:
-- `WORLD_FILE`
-- `OVERRIDES`
-
-Other configuration available:
-- `CF_PARALLEL_DOWNLOADS` (default is 4): specify how many parallel mod downloads to perform
-- `CF_OVERRIDES_SKIP_EXISTING` (default is false): if set, files in the overrides that already exist in the data directory are skipped. **NOTE** world data is always skipped, if present.
-
-## Old approach
-
-Enable this server mode by adding `-e TYPE=CURSEFORGE` to your command-line,
-but note the following additional steps needed...
-
-You need to specify a modpack to run, using the `CF_SERVER_MOD` environment
-variable. A CurseForge server modpack is available together with its respective
-client modpack at <https://www.curseforge.com/minecraft/modpacks> .
-
-Now you can add a `-e CF_SERVER_MOD=name_of_modpack.zip` to your command-line.
-
-    docker run -d -v /path/on/host:/data -e TYPE=CURSEFORGE \
-        -e CF_SERVER_MOD=SkyFactory_4_Server_4.1.0.zip \
-        -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
-
-If you want to keep the pre-download modpacks separate from your data directory,
-then you can attach another volume at a path of your choosing and reference that.
-The following example uses `/modpacks` as the container path as the pre-download area:
-
-    docker run -d -v /path/on/host:/data -v /path/to/modpacks:/modpacks \
-        -e TYPE=CURSEFORGE \
-        -e CF_SERVER_MOD=/modpacks/SkyFactory_4_Server_4.1.0.zip \
-        -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
-
-### Modpack data directory
-
-By default, CurseForge modpacks are expanded into the sub-directory `/data/FeedTheBeast` and executed from there. (The default location was chosen for legacy reasons, when Curse and FTB were maintained together.)
-
-The directory can be changed by setting `CF_BASE_DIR`, such as `-e CF_BASE_DIR=/data`.
-
-### Buggy start scripts
-
-Some modpacks have buggy or overly complex start scripts. You can avoid using the bundled start script and use this image's standard server-starting logic by adding `-e USE_MODPACK_START_SCRIPT=false`.
-
-### Fixing "unable to launch forgemodloader"
-
-If your server's modpack fails to load with an error [like this](https://support.feed-the-beast.com/t/cant-start-crashlanding-server-unable-to-launch-forgemodloader/6028/2):
-
-    unable to launch forgemodloader
-
-then you apply a workaround by adding this to the run invocation:
-
-    -e FTB_LEGACYJAVAFIXER=true
-
-## ForgeAPI usage to use non-version specific projects
-
-!!! warning "Deprecated"
-    This approach will soon be deprecated in favor of a variation of `AUTO_CURSEFORGE` mechanism described above.
-
-!!! warning
-    This potentially could lead to unexpected behavior if the Mod receives an update with unexpected behavior.
-
-This is more complicated because you will be pulling/using the latest mod for the release of your game. To get started make sure you have a [CursedForge API Key](https://docs.curseforge.com/#getting-started). Then use the environmental parameters in your docker build.
-
-Please be aware of the following when using these options for your mods:
-* Mod Release types: Release, Beta, and Alpha.
-* Mod dependencies: Required and Optional
-* Mod family: Fabric, Forge, and Bukkit.
-
-Parameters to use the ForgeAPI:
-
-* `MODS_FORGEAPI_KEY` - Required
-* `MODS_FORGEAPI_FILE` - Required or use MODS_FORGEAPI_PROJECTIDS (Overrides MODS_FORGEAPI_PROJECTIDS)
-* `MODS_FORGEAPI_PROJECTIDS` - Required or use MODS_FORGEAPI_FILE
-* `MODS_FORGEAPI_RELEASES` - Default is release, Options: [Release|Beta|Alpha]
-* `MODS_FORGEAPI_DOWNLOAD_DEPENDENCIES` - Default is False, attempts to download required mods (releaseType Release) defined in Forge.
-* `MODS_FORGEAPI_IGNORE_GAMETYPE` - Default is False, Allows for filtering mods on family type: FORGE, FABRIC, and BUKKIT. (Does not filter for Vanilla or custom)
-* `REMOVE_OLD_FORGEAPI_MODS` - Default is False
-* `REMOVE_OLD_DATAPACKS_DEPTH` - Default is 1
-* `REMOVE_OLD_DATAPACKS_INCLUDE` - Default is *.jar
-
-Example of expected forge api project ids, releases, and key:
-
-```yaml
-  MODS_FORGEAPI_PROJECTIDS: 306612,256717
-  MODS_FORGEAPI_RELEASES: Release
-  MODS_FORGEAPI_KEY: $WRX...
-```
-
-Example of expected ForgeAPI file format.
-
-**Field Description**:
-* `name` is currently unused, but can be used to document each entry.
-* `projectId` id is the id found on the CurseForge website for a particular mod
-* `releaseType` Type corresponds to forge's R, B, A icon for each file. Default Release, options are (release|beta|alpha).
-* `fileName` is used for version pinning if latest file will not work for you.
-
-```json
-[
-  {
-      "name": "fabric api",
-      "projectId": "306612",
-      "releaseType": "release"
-  },
-  {
-      "name": "fabric voice mod",
-      "projectId": "416089",
-      "releaseType": "beta"
-  },
-  {
-      "name": "Biomes o plenty",
-      "projectId": "220318",
-      "fileName": "BiomesOPlenty-1.18.1-15.0.0.100-universal.jar",
-      "releaseType": "release"
-  }
-]
-```
+# Auto CurseForge
+
+To manage a CurseForge modpack automatically with upgrade support, pinned or latest version tracking, set `MOD_PLATFORM` or `TYPE` to "AUTO_CURSEFORGE". The appropriate mod loader (Forge / Fabric) version will be automatically installed as declared by the modpack. This mode will also take care of cleaning up unused files installed by previous versions of the modpack, but world data is never auto-removed.
+
+## API Key
+
+!!! warning "CurseForge API key usage"
+
+    A CurseForge API key is **required** to use this feature. Go to their [developer console](https://console.curseforge.com/), generate an API key, and set the environment variable `CF_API_KEY`.
+    
+    When entering your API Key in a docker compose file you will need to escape any `$` character with a second `$`.
+    
+    Example if your key is `$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa`:
+    ```yaml
+    environment:
+      CF_API_KEY: '$$11$$22$$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
+    ```
+    If you use `docker run` you will need to make sure to use single quotes:
+    
+    ```shell
+    docker run ... -e CF_API_KEY='$11$22$33aaaaaaaaaaaaaaaaaaaaaaaaaa'
+    ```
+    
+    To avoid exposing the API key, it is highly recommended to use a `.env` file, which is [loaded automatically by docker compose](https://docs.docker.com/compose/environment-variables/set-environment-variables/#substitute-with-an-env-file). `$`'s in the value still need to escaped with a second `$` and the variable needs to be referenced from the compose file, such as:
+    ```yaml
+    environment:
+      CF_API_KEY: ${CF_API_KEY}
+    ```
+    
+    To use the equivalent with `docker run` you need to specify the `.env` file explicitly:
+    ```
+    docker run --env-file=.env itzg/minecraft-server
+    ```
+
+!!! note
+    Be sure to use the appropriate [image tag for the Java version compatible with the modpack](../../versions/java.md).
+    
+    Most modpacks require a good amount of memory, so it best to set `MEMORY` to at least "4G" since the default is only 1 GB.
+
+## Usage
+
+Use one of the following to specify the modpack to install:
+
+Pass a page URL to the modpack or a specific file with `CF_PAGE_URL` such as the modpack page "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8" or a specific file "https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390". For example:
+
+```
+-e TYPE=AUTO_CURSEFORGE -e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8
+```
+
+Instead of a URL, the modpack slug can be provided as `CF_SLUG`. The slug is the short identifier visible in the URL after "/modpacks/", such as
+
+![cf-slug](../../img/cf-slug.png)
+
+For example:
+```
+-e TYPE=AUTO_CURSEFORGE -e CF_SLUG=all-the-mods-8
+```
+
+For mod, modpacks, and world files that are not allowed for automated download, the container path `/downloads` can be attached and matching files will be retrieved from there. The subdirectories `mods`, `modpacks`, and `worlds` will also be checked accordingly. To change the source location of downloaded files, set `CF_DOWNLOADS_REPO` to an existing container path. To disable this feature, set `CF_DOWNLOADS_REPO` to an empty string.
+
+If the authors of the modpack have disallowed project distribution, then the desired **client** modpack zip will need to be manually downloaded and made available to the container. The path to that file must be passed to `CF_MODPACK_ZIP`. Similarly, the container path to a modpack manifest JSON can be passed to `CF_MODPACK_MANIFEST`.  In either case, the modpack slug or page URL must still be provided.
+
+The latest file will be located and used by default, but if a specific version is desired you can use one of the following options. With any of these options **do not select a server file** -- they lack the required manifest and defeat the ability to consistently automate startup.
+
+- Use `CF_PAGE_URL`, but include the full URL to a specific file
+- Set `CF_FILE_ID` to the numerical file ID
+- Specify a substring to match the desired filename with `CF_FILENAME_MATCHER`
+
+The following shows where to get the URL to the specific file and also shows where the file ID is located:
+
+![cf-file-id](../../img/cf-file-id.png)
+
+The following examples all refer to version 1.0.7 of ATM8:
+
+```
+-e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390
+```
+
+```
+-e CF_SLUG=all-the-mods-8 -e CF_FILE_ID=4248390
+```
+
+```
+-e CF_SLUG=all-the-mods-8 -e CF_FILENAME_MATCHER=1.0.7
+```
+
+## Exlude client mods
+
+Quite often there are mods that need to be excluded, such as ones that did not properly declare as a client mod via the file's game versions. Similarly, there are some mods that are incorrectly tagged as client only. The following describes two options to exclude/include mods:
+
+Mods can be excluded by passing a comma or space delimited list of **project** slugs or IDs via `CF_EXCLUDE_MODS`. Similarly, there are some mods that are incorrectly tagged as client only. For those, pass the **project** slugs or IDs via `CF_FORCE_INCLUDE_MODS`. These lists will be combined with the content of the exclude/include file, if given.
+
+A mod's project ID can be obtained from the right hand side of the project page:
+![cf-project-id](../../img/cf-project-id.png)
+
+For more complex scenarios, global and per modpack exclusions can be declared in a container-accessible JSON file and referenced with `CF_EXCLUDE_INCLUDE_FILE`. By default, [the file bundled with the image](https://raw.githubusercontent.com/itzg/docker-minecraft-server/master/files/cf-exclude-include.json) will be used, but can be disabled by setting this to an empty string. The schema of this file [is documented here](https://github.com/itzg/mc-image-helper#excludeinclude-file-schema).
+
+If needing to iterate on the options above, set `CF_FORCE_SYNCHRONIZE` to "true" to ensure the exclude/includes are re-evaluated.
+
+!!! important
+These options are provided to empower you to get your server up and running quickly. Please help out by reporting an issue with the respective mod project. Ideally mod developers should [use correct registrations for one-sided client mods](https://docs.minecraftforge.net/en/latest/concepts/sides/#writing-one-sided-mods). Understandably, those code changes may be non-trivial, so mod authors can also add "Client" to the game versions when publishing.
+
+## Extra options
+
+Some modpacks come with world/save data via a worlds file and/or the overrides provided with the modpack. Either approach can be selected to set the `LEVEL` to the resulting saves directory by setting `CF_SET_LEVEL_FROM` to either:
+- `WORLD_FILE`
+- `OVERRIDES`
+
+Other configuration available:
+- `CF_PARALLEL_DOWNLOADS` (default is 4): specify how many parallel mod downloads to perform
+- `CF_OVERRIDES_SKIP_EXISTING` (default is false): if set, files in the overrides that already exist in the data directory are skipped. **NOTE** world data is always skipped, if present.

docs/types-and-platforms/mod-platforms/curseforge.md

@@ -0,0 +1,42 @@
+# Manual CurseForge server packs
+
+Enable this server mode by setting `MOD_PLATFORM` or `TYPE` to "CURSEFORGE" along with the following specific variables.
+
+You need to specify a modpack to run, using the `CF_SERVER_MOD` environment
+variable. A CurseForge server modpack is available together with its respective
+client modpack at <https://www.curseforge.com/minecraft/modpacks> .
+
+Now you can add a `-e CF_SERVER_MOD=name_of_modpack.zip` to your command-line.
+
+    docker run -d -v /path/on/host:/data -e TYPE=CURSEFORGE \
+        -e CF_SERVER_MOD=SkyFactory_4_Server_4.1.0.zip \
+        -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
+
+If you want to keep the pre-download modpacks separate from your data directory,
+then you can attach another volume at a path of your choosing and reference that.
+The following example uses `/modpacks` as the container path as the pre-download area:
+
+    docker run -d -v /path/on/host:/data -v /path/to/modpacks:/modpacks \
+        -e TYPE=CURSEFORGE \
+        -e CF_SERVER_MOD=/modpacks/SkyFactory_4_Server_4.1.0.zip \
+        -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
+
+### Modpack data directory
+
+By default, CurseForge modpacks are expanded into the sub-directory `/data/FeedTheBeast` and executed from there. (The default location was chosen for legacy reasons, when Curse and FTB were maintained together.)
+
+The directory can be changed by setting `CF_BASE_DIR`, such as `-e CF_BASE_DIR=/data`.
+
+### Buggy start scripts
+
+Some modpacks have buggy or overly complex start scripts. You can avoid using the bundled start script and use this image's standard server-starting logic by adding `-e USE_MODPACK_START_SCRIPT=false`.
+
+### Fixing "unable to launch forgemodloader"
+
+If your server's modpack fails to load with an error [like this](https://support.feed-the-beast.com/t/cant-start-crashlanding-server-unable-to-launch-forgemodloader/6028/2):
+
+    unable to launch forgemodloader
+
+then you apply a workaround by adding this to the run invocation:
+
+    -e FTB_LEGACYJAVAFIXER=true

docs/types-and-platforms/mod-platforms/ftb.md

@@ -1,8 +1,14 @@
+# Feed the Beast
+
 !!! note
+    Requires one of the Ubuntu with Hotspot images listed in [the Java versions section](../../versions/java.md).
 
-    Requires one of the Ubuntu with Hotspot images listed in [the Java versions section](../versions/java.md).
+[Feed the Beast application](https://www.feed-the-beast.com/) modpacks are supported by setting `MOD_PLATFORM` or `TYPE` to "FTBA"
 
-[Feed the Beast application](https://www.feed-the-beast.com/) modpacks are supported by using `-e TYPE=FTBA` (**note** the "A" at the end of the type). This server type will automatically take care of downloading and installing the modpack and appropriate version of Forge, so the `VERSION` does not need to be specified.
+!!! note
+    The "A" at the end of "FTBA" is important. The value "FTB" used to be an alias for "CURSEFORGE".
+
+This mod platform type will automatically take care of downloading and installing the modpack and appropriate version of Forge, so the `VERSION` does not need to be specified.
 
 ### Environment Variables:
 - `FTB_MODPACK_ID`: **required**, the numerical ID of the modpack to install. The ID can be located by [finding the modpack](https://www.feed-the-beast.com/modpack) and locating the ID in this part of the URL:
@@ -11,7 +17,7 @@
   https://www.feed-the-beast.com/modpacks/23-ftb-infinity-evolved-17
                                           ^^
   ```
-- `FTB_MODPACK_VERSION_ID`: optional, the numerical ID of the version to install. If not specified, the latest version will be installed. The "Version ID" can be obtained by hovering over a server file entry and grabbing [this ID in the URL](../img/ftba-version-id-popup.png).
+- `FTB_MODPACK_VERSION_ID`: optional, the numerical ID of the version to install. If not specified, the latest version will be installed. The "Version ID" can be obtained by hovering over a server file entry and grabbing [this ID in the URL](../../img/ftba-version-id-popup.png).
 
 ### Upgrading
 

docs/types-and-platforms/mod-platforms/modrinth-modpacks.md

@@ -1,13 +1,15 @@
-[Modrinth Modpacks](https://modrinth.com/modpacks) can automatically be installed along with the required mod loader (Forge or Fabric) by setting `TYPE` to "MODRINTH". Upgrading (and downgrading) takes care of cleaning up old files and upgrading (and downgrading) the mod loader.
+# Modrinth Modpacks
+
+[Modrinth Modpacks](https://modrinth.com/modpacks) can automatically be installed along with the required mod loader (Forge or Fabric) by setting `MOD_PLATFORM` or `TYPE` to "MODRINTH". Upgrading (and downgrading) takes care of cleaning up old files and upgrading (and downgrading) the mod loader.
 
 The desired modpack project is specified with the `MODRINTH_PROJECT` environment variable and must be one of:
 
 - The project "slug", which is located in the URL shown here:
 
-  ![](../img/modrinth-project-slug.drawio.png)
+  ![](../../img/modrinth-project-slug.drawio.png)
 - The project ID, which is located in the bottom of the left panel, shown here
 
-  ![](../img/modrinth-project-id.drawio.png)
+  ![](../../img/modrinth-project-id.drawio.png)
 - The project page URL, such as <https://modrinth.com/modpack/cobblemon-fabric>. As described below, this can further be the page URL of a modpack's version page.
 
 The automatic modpack version resolving can be narrowed in a few ways:
@@ -20,4 +22,4 @@ The selected version can also be narrowed to a particular mod loader by setting
 
 Instead of auto resolving, a specific version of modpack file can be specified by passing the version's page URL to `MODRINTH_PROJECT`, such as <https://modrinth.com/modpack/cobblemon-fabric/version/1.3.2> or by setting `MODRINTH_VERSION` to the version ID or number located in the Metadata section, as shown here
 
-![](../img/modrinth-version-id.drawio.png)
+![](../../img/modrinth-version-id.drawio.png)

docs/types-and-platforms/server-types/bukkit-spigot.md

@@ -1,3 +1,5 @@
+# Bukkit/Spigot
+
 Enable Bukkit/Spigot server mode by adding a `-e TYPE=BUKKIT` or `-e TYPE=SPIGOT` to your command-line.
 
 ```
@@ -15,9 +17,9 @@ If you are hosting your own copy of Bukkit/Spigot you can override the download
 
 You can build spigot from source by adding `-e BUILD_FROM_SOURCE=true`
 
-Plugins can either be managed within the `plugins` subdirectory of the [data directory](../data-directory.md) or you can also [attach a `/plugins` volume](../mods-and-plugins/index.md#optional-plugins-mods-and-config-attach-points). If you add plugins while the container is running, you'll need to restart it to pick those up.
+Plugins can either be managed within the `plugins` subdirectory of the [data directory](../../data-directory.md) or you can also [attach a `/plugins` volume](../../mods-and-plugins/index.md#optional-plugins-mods-and-config-attach-points). If you add plugins while the container is running, you'll need to restart it to pick those up.
 
-[You can also auto-download plugins using `SPIGET_RESOURCES`.](../mods-and-plugins/index.md#auto-downloading-spigotmcbukkitpapermc-plugins-with-spiget)
+[You can also auto-download plugins using `SPIGET_RESOURCES`.](../../mods-and-plugins/spiget.md)
 
 !!! note
 

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

@@ -24,4 +24,4 @@ docker run -d -v /path/on/host:/data ... \
     - Provide the path to a custom launcher jar available to the container with `FABRIC_LAUNCHER`, relative to `/data` (such as `-e FABRIC_LAUNCHER=fabric-server-custom.jar`)
     - Provide the URL to a custom launcher jar with `FABRIC_LAUNCHER_URL` (such as `-e FABRIC_LAUNCHER_URL=http://HOST/fabric-server-custom.jar`)
 
-See the [Working with mods and plugins](../mods-and-plugins/index.md) section to set up Fabric mods and configuration.
+See the [Working with mods and plugins](../../mods-and-plugins/index.md) section to set up Fabric mods and configuration.

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

@@ -1,6 +1,6 @@
 Enable [Forge server](http://www.minecraftforge.net/) mode by adding a `-e TYPE=FORGE` to your command-line.
 
-The overall version is specified by `VERSION`, [as described in the section above](../versions/minecraft.md) and will run the recommended Forge version by default. You can also choose to run a specific Forge version with `FORGE_VERSION`, such as `-e FORGE_VERSION=14.23.5.2854`.
+The overall version is specified by `VERSION`, [as described in the section above](../../versions/minecraft.md) and will run the recommended Forge version by default. You can also choose to run a specific Forge version with `FORGE_VERSION`, such as `-e FORGE_VERSION=14.23.5.2854`.
 
 ```
 docker run -d -v /path/on/host:/data \

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

@@ -6,7 +6,7 @@ Enable SpongeVanilla server mode by adding a `-e TYPE=SPONGEVANILLA` to your com
 By default the container will run the latest `STABLE` version.
 If you want to run a specific version, you can add `-e SPONGEVERSION=1.11.2-6.1.0-BETA-19` to your command-line.
 
-Beware that current [Sponge](https://www.spongepowered.org) `STABLE` versions for Minecraft 1.12 require using [the Java 8 tag](../versions/java.md):
+Beware that current [Sponge](https://www.spongepowered.org) `STABLE` versions for Minecraft 1.12 require using [the Java 8 tag](../../versions/java.md):
 
 ``` shell
 docker run -d -v /path/on/host:/data -e TYPE=SPONGEVANILLA \

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

@@ -8,9 +8,9 @@ By default, the container will run the latest build of [Paper server](https://pa
 
 If you are hosting your own copy of Paper you can override the download URL with `PAPER_DOWNLOAD_URL=<url>`.
 
-If you have attached a host directory to the `/data` volume, then you can install plugins via the `plugins` subdirectory. You can also [attach a `/plugins` volume](../mods-and-plugins/index.md#optional-plugins-mods-and-config-attach-points). If you add plugins while the container is running, you'll need to restart it to pick those up.
+If you have attached a host directory to the `/data` volume, then you can install plugins via the `plugins` subdirectory. You can also [attach a `/plugins` volume](../../mods-and-plugins/index.md#optional-plugins-mods-and-config-attach-points). If you add plugins while the container is running, you'll need to restart it to pick those up.
 
-[You can also auto-download plugins using `SPIGET_RESOURCES`.](../mods-and-plugins/index.md#auto-downloading-spigotmcbukkitpapermc-plugins-with-spiget)
+[You can also auto-download plugins using `SPIGET_RESOURCES`.](../../mods-and-plugins/spiget.md)
 
 ## Alternatives
 
@@ -57,9 +57,9 @@ By default, the container will run the latest build of [Folia server](https://pa
 
 If you are hosting your own copy of Folia you can override the download URL with `FOLIA_DOWNLOAD_URL=<url>`.
 
-If you have attached a host directory to the `/data` volume, then you can install plugins via the `plugins` subdirectory. You can also [attach a `/plugins` volume](../mods-and-plugins/index.md#optional-plugins-mods-and-config-attach-points). If you add plugins while the container is running, you'll need to restart it to pick those up.
+If you have attached a host directory to the `/data` volume, then you can install plugins via the `plugins` subdirectory. You can also [attach a `/plugins` volume](../../mods-and-plugins/index.md#optional-plugins-mods-and-config-attach-points). If you add plugins while the container is running, you'll need to restart it to pick those up.
 
-[You can also auto-download plugins using `SPIGET_RESOURCES`.](../mods-and-plugins/index.md#auto-downloading-spigotmcbukkitpapermc-plugins-with-spiget)
+[You can also auto-download plugins using `SPIGET_RESOURCES`.](../../mods-and-plugins/spiget.md)
 
 !!! note
     The Folia type inherits from the Paper type. Paper's variables will override the Folia ones.

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

@@ -24,4 +24,4 @@ docker run -d -v /path/on/host:/data ... \
     - Provide the path to a custom launcher jar available to the container with `QUILT_LAUNCHER`, relative to `/data` (such as `-e QUILT_LAUNCHER=quilt-server-custom.jar`)
     - Provide the URL to a custom launcher jar with `QUILT_LAUNCHER_URL` (such as `-e QUILT_LAUNCHER_URL=http://HOST/quilt-server-custom.jar`)
 
-See the [Working with mods and plugins](../mods-and-plugins/index.md) section to set up Quilt mods and configuration.
+See the [Working with mods and plugins](../../mods-and-plugins/index.md) section to set up Quilt mods and configuration.

docs/variables/index.md

@@ -122,7 +122,7 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
     <tbody>
         <tr>
             <td><code>TYPE</code></td>
-            <td>The server <a href="java/server-types/">type</a></td>
+            <td>The server <a href="../types-and-platforms/">type</a></td>
             <td><code>VANILLA</code></td>
             <td>⬜️</td>
         </tr>
@@ -541,7 +541,7 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
         <tr>
             <td><code>RCON_PASSWORD</code></td>
             <td>You <strong>MUST</strong> change this value</td>
-            <td><code>minecraft</code></td>
+            <td><code>Randomly generated</code></td>
             <td>✅</td>
         </tr>
         <tr>

docs/versions/java.md

@@ -4,6 +4,13 @@
 
     For Forge versions less than 1.18, you _must_ use the `java8-multiarch` (or other java8) image tag.
 
+    In general, if you see the following line in a server startup failure, then it means you need to be using Java 8 instead of the latest image Java version:
+
+    ```
+    Caused by: java.lang.ClassCastException: class jdk.internal.loader.ClassLoaders$AppClassLoader 
+       cannot be cast to class java.net.URLClassLoader
+    ```
+
 When using the image `itzg/minecraft-server` without a tag, the `latest` image tag is implied from the table below. To use a different version of Java, please use an alternate tag to run your Minecraft server container.
 
 | Tag name          | Java version | Linux  | JVM Type    | Architecture      |
@@ -23,7 +30,7 @@ When using the image `itzg/minecraft-server` without a tag, the `latest` image t
 | java17-graalvm-ce | 17           | Oracle | GraalVM CE  | amd64,arm64       |
 | java17-alpine     | 17           | Alpine | Hotspot     | amd64             |
 | java20-alpine     | 19           | Alpine | Hotspot     | amd64             |
-| java20            | 19           | Ubuntu | Hotspot     | amd64,arm64 |
+| java20            | 19           | Ubuntu | Hotspot     | amd64,arm64       |
 
 For example, to use Java version 8 on any supported architecture:
 

examples/atm8/docker-compose.yml

@@ -7,7 +7,7 @@ services:
       - "25565:25565"
     environment:
       EULA: "true"
-      TYPE: AUTO_CURSEFORGE
+      MOD_PLATFORM: AUTO_CURSEFORGE
       # allocate from https://console.curseforge.com/ and set in .env file
       CF_API_KEY: ${CF_API_KEY}
       CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/all-the-mods-8

examples/docker-compose-fabric.yml

@@ -2,12 +2,12 @@ version: "3"
 
 services:
   mc:
-    image: ${IMAGE:-itzg/minecraft-server}
+    image: itzg/minecraft-server
     environment:
       EULA: "true"
       TYPE: FABRIC
     ports:
-      - 25565:25565
+      - "25565:25565"
     volumes:
       - fabric:/data
 

examples/geyser/docker-compose.yml

@@ -0,0 +1,16 @@
+version: "3.8"
+
+services:
+  mc:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "true"
+      TYPE: "PAPER"
+      PLUGINS: |
+        https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot
+        https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/spigot
+    ports:
+      - "25565:25565"
+      - "19132:19132/udp"
+    volumes:
+      - ./data:/data

examples/modrinth-modpack/docker-compose.yml

@@ -9,7 +9,7 @@ services:
       - "25565:25565"
     environment:
       EULA: "TRUE"
-      TYPE: MODRINTH
+      MOD_PLATFORM: MODRINTH
       MODRINTH_PROJECT: https://modrinth.com/modpack/cobblemon-fabric/version/1.3.2
       # or for auto-upgrading to latest
       # MODRINTH_PROJECT: https://modrinth.com/modpack/cobblemon-fabric
@@ -18,7 +18,6 @@ services:
       # MODRINTH_VERSION: nvrqJg44
       # MODRINTH_VERSION: 1.3.2
       # MODRINTH_VERSION: "Cobblemon [Fabric] 1.3.2"
-      SETUP_ONLY: "true"
     volumes:
       # attach the relative directory 'data' to the container's /data path
       - ./data:/data

examples/modrinth-paper/docker-compose.yml

@@ -2,7 +2,7 @@ version: "3"
 
 services:
   mc:
-    image: ${IMAGE_TO_TEST:-itzg/minecraft-server}
+    image: itzg/minecraft-server
     environment:
       EULA: "true"
       TYPE: PAPER

examples/one-block-modded/docker-compose.yml

@@ -7,7 +7,7 @@ services:
       - "25565:25565"
     environment:
       EULA: "true"
-      TYPE: AUTO_CURSEFORGE
+      MOD_PLATFORM: AUTO_CURSEFORGE
       # CF_API_KEY=... must be set in .env file or as environment variable
       CF_API_KEY: ${CF_API_KEY}
       CF_SLUG: one-block-modded

examples/pixelmon/docker-compose.yml

@@ -7,7 +7,7 @@ services:
       - "25565:25565"
     environment:
       EULA: "true"
-      TYPE: AUTO_CURSEFORGE
+      MOD_PLATFORM: AUTO_CURSEFORGE
       CF_API_KEY: # allocate from https://console.curseforge.com/
       CF_SLUG: the-pixelmon-modpack
       CF_FILENAME_MATCHER: "9.1.2"

examples/quilt/docker-compose.yml

@@ -0,0 +1,15 @@
+version: "3"
+
+services:
+  mc:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "true"
+      TYPE: QUILT
+    ports:
+      - "25565:25565"
+    volumes:
+      - data:/data
+
+volumes:
+  data: {}

examples/valhesia5/docker-compose.yml

@@ -7,7 +7,7 @@ services:
       - "25565:25565"
     environment:
       EULA: "true"
-      TYPE: AUTO_CURSEFORGE
+      MOD_PLATFORM: AUTO_CURSEFORGE
       CF_API_KEY: # allocate from https://console.curseforge.com/
       CF_FORCE_SYNCHRONIZE: "true"
       CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/valhelsia-5/files/4429560

examples/vault-hunters-1-18-2/docker-compose.yml

@@ -7,7 +7,7 @@ services:
       - "25565:25565"
     environment:
       EULA: "true"
-      TYPE: AUTO_CURSEFORGE
+      MOD_PLATFORM: AUTO_CURSEFORGE
       CF_API_KEY: # allocate from https://console.curseforge.com/
       CF_SLUG: vault-hunters-1-18-2
       CF_FILENAME_MATCHER: "Update-10.0.0"

files/cf-exclude-include.json

@@ -4,7 +4,6 @@
     "armor-toughness-bar",
     "biomeinfo",
     "block-drops-jei-addon",
-    "carry-on",
     "cherished-worlds",
     "controlling",
     "ctm",

kustomize/base/kustomization.yml

@@ -1,3 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
 resources:
 - statefulset.yml
 - service.yml

scripts/start-configuration

@@ -105,35 +105,12 @@ function fixJavaPath() {
   fi
 }
 
+
 if ! fixJavaPath; then
   log "ERROR: could not locate path that contains java"
   exit 1
 fi
 
-export VERSIONS_JSON=https://launchermeta.mojang.com/mc/game/version_manifest.json
-
-case "X$VERSION" in
-  X|XLATEST|Xlatest)
-    if ! VANILLA_VERSION=$(get --json-path '$.latest.release' "$VERSIONS_JSON"); then
-      log "ERROR: version lookup failed: $VANILLA_VERSION"
-      exit 1
-    fi
-  ;;
-  XSNAPSHOT|Xsnapshot)
-    if ! VANILLA_VERSION=$(get --json-path '$.latest.snapshot' "$VERSIONS_JSON"); then
-      log "ERROR: version lookup failed: $VANILLA_VERSION"
-      exit 1
-    fi
-  ;;
-  *)
-    VANILLA_VERSION=$VERSION
-  ;;
-esac
-export VANILLA_VERSION
-MAJOR_VANILLA_VERSION=$(get_major_version "$VANILLA_VERSION")
-export MAJOR_VANILLA_VERSION
-log "Resolved version given ${VERSION} into ${VANILLA_VERSION} and major version ${MAJOR_VANILLA_VERSION}"
-
 cd /data || exit 1
 
 export ORIGINAL_TYPE=${TYPE^^}
@@ -158,12 +135,31 @@ then
   "${SCRIPTS:-/}start-rconcmds"
 fi
 
-if versionLessThan 1.7; then
-  echo "
-MC_HEALTH_EXTRA_ARGS=(
-  --use-server-list-ping
-)
-  " > /data/.mc-health.env
+: ${MOD_PLATFORM:=}
+case "${TYPE^^}" in
+  AUTO_CURSEFORGE|MODRINTH|CURSEFORGE|FTB|FTBA)
+    MOD_PLATFORM="$TYPE"
+  ;;
+esac
+
+if [[ $MOD_PLATFORM ]]; then
+  case "${MOD_PLATFORM^^}" in
+    FTB|CURSEFORGE)
+      exec "${SCRIPTS:-/}start-deployCF" "$@"
+    ;;
+
+    FTBA)
+      exec "${SCRIPTS:-/}start-deployFTBA" "$@"
+    ;;
+
+    AUTO_CURSEFORGE)
+      exec "${SCRIPTS:-/}start-deployAutoCF" "$@"
+      ;;
+
+    MODRINTH)
+      exec "${SCRIPTS:-/}start-deployModrinth" "$@"
+      ;;
+  esac
 fi
 
 log "Resolving type given ${TYPE}"
@@ -181,7 +177,6 @@ case "${TYPE^^}" in
   ;;
 
   FORGE)
-    evaluateJavaCompatibilityForForge
     exec "${SCRIPTS:-/}start-deployForge" "$@"
   ;;
 
@@ -193,25 +188,6 @@ case "${TYPE^^}" in
     exec "${SCRIPTS:-/}start-deployQuilt" "$@"
   ;;
   
-  FTBA)
-    evaluateJavaCompatibilityForForge
-    exec "${SCRIPTS:-/}start-deployFTBA" "$@"
-  ;;
-
-  FTB|CURSEFORGE)
-    evaluateJavaCompatibilityForForge
-    exec "${SCRIPTS:-/}start-deployCF" "$@"
-  ;;
-
-  AUTO_CURSEFORGE)
-    evaluateJavaCompatibilityForForge
-    exec "${SCRIPTS:-/}start-deployAutoCF" "$@"
-    ;;
-
-  MODRINTH)
-    exec "${SCRIPTS:-/}start-deployModrinth" "$@"
-    ;;
-
   VANILLA)
     exec "${SCRIPTS:-/}start-deployVanilla" "$@"
   ;;
@@ -257,12 +233,6 @@ case "${TYPE^^}" in
   ;;
 
   CRUCIBLE)
-    log "**********************************************************************"
-    log "WARNING: The image tag itzg/minecraft-server:java8 is recommended"
-    log "         since some mods require Java 8"
-    log "         Exception traces reporting ClassCastException: class jdk.internal.loader.ClassLoaders\$AppClassLoader"
-    log "         can be fixed with java8"
-    log "**********************************************************************"
     exec "${SCRIPTS:-/}start-deployCrucible" "$@"
   ;;
 

scripts/start-deployAutoCF

@@ -66,13 +66,11 @@ if ! mc-image-helper install-curseforge "${args[@]}"; then
     exit 1
 fi
 
-# grab SERVER, FAMILY and export it
+# grab SERVER, TYPE, VERSION and export it
 set -a
 # shellcheck disable=SC1090
 source "${resultsFile}"
 set +a
-# grab the version resolved from modpack
-VANILLA_VERSION="$VERSION"
-export VANILLA_VERSION
+resolveFamily
 
 exec "${SCRIPTS:-/}start-setupWorld" "$@"

scripts/start-deployBukkitSpigot

@@ -1,6 +1,7 @@
 #!/bin/bash
 
-. ${SCRIPTS:-/}start-utils
+# shellcheck source=start-utils
+. "${SCRIPTS:-/}start-utils"
 isDebugging && set -x
 
 set -e
@@ -60,14 +61,14 @@ function downloadSpigot {
   esac
 
   if [[ ${VERSION^^} = LATEST ]]; then
-    VANILLA_VERSION=$(restify https://getbukkit.org/download/spigot --attribute='property=og:title' | jq -r '.[0] | .attributes | select(.property == "og:title") | .content | split(" ") | .[-1]')
+    VERSION=$(restify https://getbukkit.org/download/spigot --attribute='property=og:title' | jq -r '.[0] | .attributes | select(.property == "og:title") | .content | split(" ") | .[-1]')
   fi
 
   if [[ -z $downloadUrl ]]; then
-    if versionLessThan 1.16.5 || ([[ ${getbukkitFlavor} = "craftbukkit" ]] && [[ ${VANILLA_VERSION} = "1.16.5" ]]); then
-      downloadUrl="https://cdn.getbukkit.org/${getbukkitFlavor}/${getbukkitFlavor}-${VANILLA_VERSION}.jar"
+    if versionLessThan 1.16.5 || ([[ ${getbukkitFlavor} = "craftbukkit" ]] && [[ ${VERSION} = "1.16.5" ]]); then
+      downloadUrl="https://cdn.getbukkit.org/${getbukkitFlavor}/${getbukkitFlavor}-${VERSION}.jar"
     else
-      downloadUrl="https://download.getbukkit.org/${getbukkitFlavor}/${getbukkitFlavor}-${VANILLA_VERSION}.jar"
+      downloadUrl="https://download.getbukkit.org/${getbukkitFlavor}/${getbukkitFlavor}-${VERSION}.jar"
     fi
   fi
 
@@ -108,15 +109,16 @@ EOF
 function setServerVar {
   case "$TYPE" in
     *BUKKIT|*bukkit)
-      export SERVER=craftbukkit_server-${VANILLA_VERSION}.jar
+      export SERVER=craftbukkit_server-${VERSION}.jar
       ;;
     *)
-      export SERVER=spigot_server-${VANILLA_VERSION}.jar
+      export SERVER=spigot_server-${VERSION}.jar
       ;;
   esac
 }
 
 if isTrue "$BUILD_SPIGOT_FROM_SOURCE" || isTrue "$BUILD_FROM_SOURCE"; then
+  resolveVersion
   setServerVar
   if [ ! -f "$SERVER" ] || isTrue "$FORCE_REDOWNLOAD"; then
     buildSpigotFromSource

scripts/start-deployCF

@@ -24,6 +24,11 @@ loadForgeVars() {
 
 isDebugging && set -x
 
+if [[ ${VERSION^^} == LATEST ]]; then
+  log "WARNING for the old TYPE=CURSEFORGE mechanism it is best to set VERSION to a specific value"
+fi
+resolveVersion
+
 : "${FTB_BASE_DIR:=${CF_BASE_DIR:-/data/FeedTheBeast}}"
 export FTB_BASE_DIR
 

scripts/start-deployCrucible

@@ -6,7 +6,7 @@ set -o pipefail
 set -e
 isDebugging && set -x
 
-requireVar VANILLA_VERSION
+resolveVersion
 : "${CRUCIBLE_RELEASE:=latest}"
 
 crucibleReleasesUrl=https://api.github.com/repos/CrucibleMC/Crucible/releases
@@ -16,14 +16,14 @@ else
   crucibleReleaseUrl=${crucibleReleasesUrl}/tags/${CRUCIBLE_RELEASE}
 fi
 
-if ! downloadUrl=$(get --json-path "$.assets[?(@.name =~ /Crucible-${VANILLA_VERSION}-.*\.jar/)].browser_download_url" \
+if ! downloadUrl=$(get --json-path "$.assets[?(@.name =~ /Crucible-${VERSION}-.*\.jar/)].browser_download_url" \
     --accept "application/vnd.github.v3+json" "$crucibleReleaseUrl"); then
   log "ERROR: failed to access ${CRUCIBLE_RELEASE} release of Crucible"
   exit 1
 fi
 
 if [[ $downloadUrl = null ]]; then
-  log "ERROR: failed to locate Crucible jar for $VANILLA_VERSION from ${CRUCIBLE_RELEASE}"
+  log "ERROR: failed to locate Crucible jar for $VERSION from ${CRUCIBLE_RELEASE}"
   exit 1
 fi
 

scripts/start-deployFabric

@@ -19,9 +19,10 @@ if [[ $FABRIC_LAUNCHER ]]; then
   if ! mc-image-helper install-fabric-loader \
     --results-file=${resultsFile} \
     --from-local-file="$FABRIC_LAUNCHER"; then
-    log "ERROR failed to install Fabric launcher from $FABRIC_LAUNCHER"
+    log "ERROR failed to use provided Fabric launcher"
     exit 1
   fi
+
 # Custom fabric jar url
 elif [[ $FABRIC_LAUNCHER_URL ]]; then
   if ! mc-image-helper install-fabric-loader \
@@ -30,19 +31,21 @@ elif [[ $FABRIC_LAUNCHER_URL ]]; then
     log "ERROR failed to install Fabric launcher from $FABRIC_LAUNCHER_URL"
     exit 1
   fi
+
 # Official fabric launcher
 else
   if ! mc-image-helper install-fabric-loader \
     --results-file=${resultsFile} \
-    --minecraft-version="${VANILLA_VERSION}" \
+    --minecraft-version="${VERSION}" \
     --installer-version="${FABRIC_LAUNCHER_VERSION}" \
     --loader-version="${FABRIC_LOADER_VERSION}"; then
-    log "ERROR failed to install Fabric launcher from $VANILLA_VERSION, $FABRIC_LAUNCHER_VERSION, $FABRIC_LOADER_VERSION"
+    log "ERROR failed to install Fabric launcher given $VERSION, $FABRIC_LAUNCHER_VERSION, $FABRIC_LOADER_VERSION"
     exit 1
   fi
+
 fi
 
-# grab SERVER and export it
+# grab SERVER, etc and export it
 set -a
 # shellcheck disable=SC1090
 source "${resultsFile}"

scripts/start-deployFolia

@@ -8,4 +8,4 @@ if [[ $FOLIABUILD ]]; then
   export PAPERBUILD="$FOLIABUILD"
 fi
 
-PAPER_PROJECT="folia" PAPER_NAME="FoliaMC" exec ${SCRIPTS:-/}start-deployPaper "$@"
+PAPER_PROJECT="folia" PAPER_NAME="FoliaMC" exec "${SCRIPTS:-/}start-deployPaper" "$@"

scripts/start-deployForge

@@ -7,8 +7,6 @@
 . "${SCRIPTS:-$(dirname "$0")}/start-utils"
 isDebugging && set -x
 
-# NOTE: VERSION rather than VANILLA_VERSION is specified to allow for latest supported
-#       Forge version to be selected.
 if [[ ${FORGE_INSTALLER} ]]; then
   if ! mc-image-helper install-forge \
     --output-directory=/data \

scripts/start-deployMagma

@@ -4,10 +4,15 @@
 . "${SCRIPTS:-/}start-utils"
 isDebugging && set -x
 
-: "${VANILLA_VERSION?}"
+resolveVersion
 
-if ! downloadUrl=$(get --json-path '$.link' "https://api.magmafoundation.org/api/v2/${VANILLA_VERSION}/latest"); then
-  log "ERROR failed to locate latest Magma download for ${VANILLA_VERSION}. Is that version supported?"
+if ! downloadUrl=$(get --json-path '$.link' "https://api.magmafoundation.org/api/v2/${VERSION}/latest"); then
+  log "ERROR failed to locate latest Magma download for ${VERSION}. Is that version supported?"
+  exit 1
+fi
+
+if [[ $downloadUrl == null ]]; then
+  log "ERROR Magma does not seem to be available for $VERSION"
   exit 1
 fi
 

scripts/start-deployModrinth

@@ -48,13 +48,11 @@ if ! mc-image-helper install-modrinth-modpack "${args[@]}"; then
     exit 1
 fi
 
-# grab SERVER, FAMILY and export it
+# grab SERVER, TYPE, VERSION and export it
 set -a
 # shellcheck disable=SC1090
 source "${resultsFile}"
 set +a
-# grab the version resolved from modpack
-VANILLA_VERSION="$VERSION"
-export VANILLA_VERSION
+resolveFamily
 
 exec "${SCRIPTS:-/}start-setupWorld" "$@"

scripts/start-deployMohist

@@ -6,14 +6,14 @@ set -o pipefail
 set -e
 isDebugging && set -x
 
-requireVar VANILLA_VERSION
+resolveVersion
 : "${MOHIST_BUILD:=lastSuccessfulBuild}"
 
 mohistJobs=https://ci.codemc.io/job/MohistMC/job/
-mohistJob=${mohistJobs}Mohist-${VANILLA_VERSION}/
+mohistJob=${mohistJobs}Mohist-${VERSION}/
 
 if ! get --exists "${mohistJob}"; then
-  log "ERROR: mohist builds do not exist for ${VANILLA_VERSION}"
+  log "ERROR: mohist builds do not exist for ${VERSION}"
   log "       check https://ci.codemc.io/job/MohistMC/ for available versions"
   log "       and set VERSION accordingly"
   exit 1
@@ -25,7 +25,7 @@ buildRelPath=$(
 
 baseName=$(basename "${buildRelPath}")
 if [[ ${baseName} != *-server.jar* ]]; then
-  log "ERROR: mohist build for ${VANILLA_VERSION} is not a valid server jar, found ${baseName}"
+  log "ERROR: mohist build for ${VERSION} is not a valid server jar, found ${baseName}"
   log "       check https://ci.codemc.io/job/MohistMC/ for available versions"
   log "       and set VERSION accordingly"
   exit 1

scripts/start-deployPaper

@@ -5,99 +5,51 @@
 set -o pipefail
 handleDebugMode
 
+: "${PAPER_PROJECT:=paper}"
+: "${PAPERBUILD:=}"
+: "${PAPER_DOWNLOAD_URL:=}"
 : "${PAPER_CUSTOM_JAR:=}"
 
-ourScript="$0"
-ourArgs=("$@")
-
-# Check if we're running Folia.
-if [[ -z $PAPER_PROJECT ]]; then
-  PAPER_PROJECT="paper"
-  PAPER_NAME="PaperMC"
-fi
-
-function handleMissingVersion() {
-  expectedVersion=${VANILLA_VERSION}
-  versions=$(curl -fsSL "https://papermc.io/api/v2/projects/${PAPER_PROJECT}" -H  "accept: application/json")
-  if [[ $VERSION = LATEST ]]; then
-    tries=0
-    while ((tries++ < 5)); do
-      VANILLA_VERSION=$(echo "$versions" | jq -r ".versions[$((- tries))]")
-      if [[ $(curl -fsSL "https://papermc.io/api/v2/projects/${PAPER_PROJECT}/versions/${VANILLA_VERSION}" -H  "accept: application/json" \
-               | jq '.builds[-1]') != null ]]; then
-        log "WARN: using ${VANILLA_VERSION} since that's the latest provided by ${PAPER_NAME}"
-        # re-execute the current script with the newly computed version
-        exec "$ourScript" "${ourArgs[@]}"
-     fi
-   done
-  fi
-  log "ERROR: ${expectedVersion} is not published by ${PAPER_NAME}"
-  log "       Set VERSION to one of the following: "
-  log "       $(echo "$versions" | jq -r '.versions | join(", ")')"
-  exit 1
-}
-
+resultsFile=/data/.paper.env
 if [[ $PAPER_CUSTOM_JAR ]]; then
   export SERVER="$PAPER_CUSTOM_JAR"
 elif [[ $PAPER_DOWNLOAD_URL ]]; then
-  export SERVER=$(getFilenameFromUrl "${PAPER_DOWNLOAD_URL}")
-
-  if [ -f "$SERVER" ]; then
-    zarg=(-z "$SERVER")
-  fi
-
-  echo "Preparing custom ${PAPER_NAME} jar from $PAPER_DOWNLOAD_URL"
-
-  curl -fsSL -o "$SERVER" "${zarg[@]}" "${PAPER_DOWNLOAD_URL}"
-else
-  # Paper API v2 docs : https://papermc.io/api/docs/swagger-ui/index.html?configUrl=/api/openapi/swagger-config
-
-  build=${PAPERBUILD:=$(curl -fsSL "https://papermc.io/api/v2/projects/${PAPER_PROJECT}/versions/${VANILLA_VERSION}" -H  "accept: application/json" \
-   | jq '.builds[-1]')}
-  case $? in
-    0)
-      ;;
-    22)
-      handleMissingVersion
-      ;;
-    *)
-      echo "ERROR: unknown error while looking up ${PAPER_NAME} version=${VANILLA_VERSION}"
+  if ! mc-image-helper install-paper \
+    --output-directory=/data \
+    --results-file="$resultsFile" \
+    --url="$PAPER_DOWNLOAD_URL"; then
+      log "ERROR: failed to download from custom PaperMC URL"
       exit 1
-      ;;
-  esac
-
-  if [[ $build = null ]]; then
-    handleMissingVersion
   fi
+  # grab SERVER and export it
+  set -a
+  # shellcheck disable=SC1090
+  source "${resultsFile}"
+  set +a
 
-  export SERVER=$(curl -fsSL "https://papermc.io/api/v2/projects/${PAPER_PROJECT}/versions/${VANILLA_VERSION}/builds/${build}" -H  "accept: application/json" \
-   | jq -r '.downloads.application.name')
-  if [ $? != 0 ]; then
-    echo "ERROR: failed to lookup ${PAPER_NAME} download file from version=${VANILLA_VERSION} build=${build}"
-    exit 1
+else
+  args=(
+    --output-directory=/data
+    --results-file="$resultsFile"
+    --project="$PAPER_PROJECT"
+    --version="$VERSION"
+  )
+  if [[ $PAPERBUILD ]]; then
+    args+=(--build="$PAPERBUILD")
   fi
-
-  if [ -f "$SERVER" ]; then
-    zarg=(-z "$SERVER")
+  if ! mc-image-helper install-paper "${args[@]}"; then
+      log "ERROR: failed to download $PAPER_PROJECT"
+      exit 1
   fi
+  # grab SERVER and export it
+  set -a
+  # shellcheck disable=SC1090
+  source "${resultsFile}"
+  set +a
 
-  log "Removing old ${PAPER_NAME} versions ..."
-  shopt -s nullglob
-  for f in paper-*.jar; do
-    [[ $f != $SERVER ]] && rm $f
-  done
-
-  log "Downloading ${PAPER_NAME} $VANILLA_VERSION (build $build) ..."
-  curl -fsSL -o "$SERVER" "${zarg[@]}" \
-    "https://papermc.io/api/v2/projects/${PAPER_PROJECT}/versions/${VANILLA_VERSION}/builds/${build}/downloads/${SERVER}" \
-    -H  "accept: application/java-archive"
-  if [ $? != 0 ]; then
-    echo "ERROR: failed to download ${PAPER_NAME} from version=${VANILLA_VERSION} build=${build} download=${SERVER}"
-    exit 1
-  fi
 fi
 
 # Normalize on Spigot for downstream operations
 export FAMILY=SPIGOT
 
-exec ${SCRIPTS:-/}start-spiget "$@"
+exec "${SCRIPTS:-/}start-spiget" "$@"

scripts/start-deployPufferfish

@@ -15,7 +15,8 @@ fi
 
 : "${PUFFERFISH_BUILD:=lastSuccessfulBuild}"
 
-PUFFERFISH_BUILD_JSON=$(curl -X GET -s "https://ci.pufferfish.host/job/Pufferfish-${MAJOR_VANILLA_VERSION}/${PUFFERFISH_BUILD}/api/json")
+majorVersion=$(get_major_version "$VERSION")
+PUFFERFISH_BUILD_JSON=$(curl -X GET -s "https://ci.pufferfish.host/job/Pufferfish-${majorVersion}/${PUFFERFISH_BUILD}/api/json")
 # Example: "url": "https://ci.pufferfish.host/job/Pufferfish-1.18/50/",
 PUFFERFISH_BUILD_URL=$(jq -n "$PUFFERFISH_BUILD_JSON" | jq -jc '.url // empty' )
 # Example: "fileName": "pufferfish-paperclip-1.18.2-R0.1-SNAPSHOT-reobf.jar",

scripts/start-deployPurpur

@@ -2,51 +2,47 @@
 set -euo pipefail
 IFS=$'\n\t'
 
+: "${PURPUR_BUILD:=LATEST}"
 : "${PURPUR_DOWNLOAD_URL:=}"
 
 # shellcheck source=start-utils
 . "${SCRIPTS:-/}start-utils"
 isDebugging && set -x
 
+resultsFile=/data/.purpur.env
+
 if [[ $PURPUR_DOWNLOAD_URL ]]; then
-  export SERVER=$(getFilenameFromUrl "${PURPUR_DOWNLOAD_URL}")
-
-  if [ -f "$SERVER" ]; then
-    zarg=(-z "$SERVER")
-  fi
-
-  echo "Preparing custom Purpur jar from $PURPUR_DOWNLOAD_URL"
-
-  curl -fsSL -o "$SERVER" "${zarg[@]}" "${PURPUR_DOWNLOAD_URL}"
-else
-  : "${VANILLA_VERSION:?}"
-  : "${PURPUR_BUILD:=LATEST}"
-  : "${FORCE_REDOWNLOAD:=false}"
-
-  if [[ ${PURPUR_BUILD} == LATEST ]]; then
-    if ! PURPUR_BUILD=$(get --json-path=".builds.latest" "https://api.purpurmc.org/v2/purpur/${VANILLA_VERSION}"); then
-      log "ERROR: Failed to locate a Purpur build for ${VANILLA_VERSION}."
-      log "       Please check if a download is available at https://purpur.pl3x.net/downloads/"
+  if ! mc-image-helper install-purpur \
+    --output-directory=/data \
+    --results-file="$resultsFile" \
+    --url="$PURPUR_DOWNLOAD_URL}"; then
+      log "ERROR: failed to download from custom Purpur URL"
       exit 1
-    fi
   fi
+  # grab SERVER and export it
+  set -a
+  # shellcheck disable=SC1090
+  source "${resultsFile}"
+  set +a
 
-  export SERVER="purpur-${VANILLA_VERSION}-${PURPUR_BUILD}.jar"
-
-  log "Removing old Purpur versions ..."
-  shopt -s nullglob
-  for f in purpur-*.jar; do
-    [[ $f != "$SERVER" ]] && rm "$f"
-  done
-
-  if [ ! -f "$SERVER" ] || isTrue "$FORCE_REDOWNLOAD"; then
-      downloadUrl="https://api.purpurmc.org/v2/purpur/${VANILLA_VERSION}/${PURPUR_BUILD}/download"
-      log "Downloading Purpur from $downloadUrl ..."
-      if ! get -o "$SERVER" "$downloadUrl"; then
-        log "ERROR: failed to download from $downloadUrl (status=$?)"
-        exit 3
-      fi
+else
+  args=(
+    --output-directory=/data
+    --results-file="$resultsFile"
+    --version="$VERSION"
+  )
+  if [[ $PURPUR_BUILD ]]; then
+    args+=(--build="$PURPUR_BUILD")
   fi
+  if ! mc-image-helper install-purpur "${args[@]}"; then
+      log "ERROR: failed to download Purpur"
+      exit 1
+  fi
+  # grab SERVER and export it
+  set -a
+  # shellcheck disable=SC1090
+  source "${resultsFile}"
+  set +a
 fi
 
 # Normalize on Spigot for later operations

scripts/start-deployQuilt

@@ -4,8 +4,6 @@ set -eu
 # shellcheck source=start-utils
 . "${SCRIPTS:-/}start-utils"
 
-requireVar VANILLA_VERSION
-export TYPE=QUILT
 : "${QUILT_LAUNCHER:=}"
 : "${QUILT_LAUNCHER_URL:=}"
 : "${QUILT_INSTALLER_URL:=}"
@@ -14,47 +12,50 @@ export TYPE=QUILT
 
 isDebugging && set -x
 
-# Custom quilt jar
+resultsFile=/data/.quilt.env
+
 if [[ $QUILT_LAUNCHER ]]; then
-  export SERVER=${QUILT_LAUNCHER}
-# Custom quilt jar url
+  log "WARNING: use of QUILT_LAUNCHER is a deprecated feature."
+  SERVER="$QUILT_LAUNCHER"
+  export SERVER
+  resolveVersion
+
+  export FAMILY=FABRIC
+  exec "${SCRIPTS:-/}start-setupWorld" "$@"
+
 elif [[ $QUILT_LAUNCHER_URL ]]; then
-  export SERVER=quilt-server-$(echo -n "$QUILT_LAUNCHER_URL" | mc-image-helper hash)
-# Official quilt installer
+  log "ERROR: QUILT_LAUNCHER_URL is not longer supported. Pre-download and use QUILT_LAUNCHER."
+  exit 2
+
+elif [[ $QUILT_INSTALLER_URL ]]; then
+  if ! mc-image-helper install-quilt \
+    --loader-version="$QUILT_LOADER_VERSION" \
+    --minecraft-version="$VERSION" \
+    --output-directory=/data \
+    --results-file="$resultsFile" \
+    --installer-url="$QUILT_INSTALLER_URL"; then
+    log "ERROR: failed to install Quilt given custom installer URL $QUILT_INSTALLER_URL"
+    exit 2
+  fi
+
 else
-  if [[ ${QUILT_INSTALLER_VERSION^^} = LATEST ]]; then
-    log "Checking Quilt Installer version information."
-    QUILT_INSTALLER_VERSION=$(maven-metadata-release https://maven.quiltmc.org/repository/release/org/quiltmc/quilt-installer/maven-metadata.xml)
+  if ! mc-image-helper install-quilt \
+    --loader-version="$QUILT_LOADER_VERSION" \
+    --minecraft-version="$VERSION" \
+    --output-directory=/data \
+    --results-file="$resultsFile" \
+    --installer-version="$QUILT_INSTALLER_VERSION"; then
+    log "ERROR: failed to install Quilt given installer version $QUILT_INSTALLER_VERSION"
+    exit 2
   fi
-  if [[ ${QUILT_LOADER_VERSION^^} = LATEST ]]; then
-    log "Checking Quilt Loader version information."
-    QUILT_LOADER_VERSION=$(maven-metadata-release https://maven.quiltmc.org/repository/release/org/quiltmc/quilt-loader/maven-metadata.xml)
-  fi
-  export INSTALLER=quilt-installer-${QUILT_INSTALLER_VERSION}.jar
-  export SERVER=quilt-server-${VANILLA_VERSION}-${QUILT_LOADER_VERSION}-launch.jar 
-  export QUILT_INSTALLER_URL="https://maven.quiltmc.org/repository/release/org/quiltmc/quilt-installer/${QUILT_INSTALLER_VERSION}/quilt-installer-${QUILT_INSTALLER_VERSION}.jar"
+
 fi
 
-if [[ ! -e ${SERVER} && ! -z ${QUILT_INSTALLER_URL} ]]; then
-  log "Downloading and installing $QUILT_INSTALLER_URL ..."
-  if ! get -o "$INSTALLER" "$QUILT_INSTALLER_URL"; then
-    log "Failed to download from given location $QUILT_INSTALLER_URL"
-    exit 2
-  fi
-  if ! java -jar ${INSTALLER} install server ${VANILLA_VERSION} ${QUILT_LOADER_VERSION} --install-dir=./ --download-server; then
-    log "Failed to install $INSTALLER"
-    exit 2
-  fi
-  if ! mv quilt-server-launch.jar ${SERVER}; then
-    log "Failed to rename $SERVER"
-    exit 2
-  fi
-fi
-
-if [[ ! -e ${SERVER} ]]; then
-  log "$SERVER does not exist, cannot launch server!"
-  exit 1
-fi
+# grab SERVER, VERSION and export it
+set -a
+# shellcheck disable=SC1090
+source "${resultsFile}"
+set +a
 
 export FAMILY=FABRIC
 exec "${SCRIPTS:-/}start-setupWorld" "$@"

scripts/start-deploySpongeVanilla

@@ -1,5 +1,6 @@
 #!/bin/bash
 
+# shellcheck source=start-utils
 . ${SCRIPTS:-/}start-utils
 
 export TYPE=spongevanilla
@@ -24,20 +25,20 @@ esac
 if [ -z $SPONGEVERSION ]; then
   log "Choosing Version for Sponge"
   if [ "$SPONGEBRANCH" == "stable" ]; then
-    SPONGEVERSION=`curl -fsSL https://dl-api.spongepowered.org/v1/org.spongepowered/$TYPE | jq -r '.buildTypes.stable.latest.version'`
+    SPONGEVERSION=$(curl -fsSL https://dl-api.spongepowered.org/v1/org.spongepowered/$TYPE | jq -r '.buildTypes.stable.latest.version')
   else
-    SPONGEVERSION=`curl -fsSL https://dl-api.spongepowered.org/v1/org.spongepowered/$TYPE | jq -r '.buildTypes.bleeding.latest.version'`
+    SPONGEVERSION=$(curl -fsSL https://dl-api.spongepowered.org/v1/org.spongepowered/$TYPE | jq -r '.buildTypes.bleeding.latest.version')
   fi
 fi
 
-VANILLA_VERSION="$SPONGEVERSION"
-export VANILLA_VERSION
+VERSION="$SPONGEVERSION"
+export VERSION
 export SERVER="spongevanilla-$SPONGEVERSION.jar"
 
-if [ ! -e $SERVER ] || [ -n "$FORCE_REDOWNLOAD" ]; then
+if [ ! -e "$SERVER" ] || [ -n "$FORCE_REDOWNLOAD" ]; then
   log "Downloading $SERVER ..."
-  curl -sSL -o $SERVER https://repo.spongepowered.org/maven/org/spongepowered/$TYPE/$SPONGEVERSION/$SERVER
+  curl -sSL -o "$SERVER" "https://repo.spongepowered.org/maven/org/spongepowered/$TYPE/$SPONGEVERSION/$SERVER"
 fi
 
 export FAMILY=SPONGE
-exec ${SCRIPTS:-/}start-setupWorld "$@"
+exec "${SCRIPTS:-/}start-setupWorld" "$@"

scripts/start-deployVanilla

@@ -5,18 +5,19 @@
 isDebugging && set -x
 set -o pipefail
 
-export SERVER="minecraft_server.${VANILLA_VERSION// /_}.jar"
+resolveVersion
+export SERVER="minecraft_server.${VERSION// /_}.jar"
 
 if [ ! -e "$SERVER" ] || [ -n "$FORCE_REDOWNLOAD" ]; then
-  debug "Finding version manifest for $VANILLA_VERSION"
-  versionManifestUrl=$(get 'https://launchermeta.mojang.com/mc/game/version_manifest.json' | jq --arg VANILLA_VERSION "$VANILLA_VERSION" --raw-output '[.versions[]|select(.id == $VANILLA_VERSION)][0].url')
+  debug "Finding version manifest for $VERSION"
+  versionManifestUrl=$(get 'https://launchermeta.mojang.com/mc/game/version_manifest.json' | jq --arg VERSION "$VERSION" --raw-output '[.versions[]|select(.id == $VERSION)][0].url')
   result=$?
   if [ $result != 0 ]; then
     log "ERROR: failed to obtain version manifest URL ($result)"
     exit 1
   fi
   if [ "$versionManifestUrl" = "null" ]; then
-    log "ERROR: couldn't find a matching manifest entry for $VANILLA_VERSION"
+    log "ERROR: couldn't find a matching manifest entry for $VERSION"
     exit 1
   fi
   debug "Found version manifest at $versionManifestUrl"
@@ -25,11 +26,11 @@ if [ ! -e "$SERVER" ] || [ -n "$FORCE_REDOWNLOAD" ]; then
     log "ERROR: failed to obtain version manifest from $versionManifestUrl ($result)"
     exit 1
   elif [ "$serverDownloadUrl" = "null" ]; then
-    log "ERROR: there is not a server download for version $VANILLA_VERSION"
+    log "ERROR: there is not a server download for version $VERSION"
     exit 1
   fi
 
-  log "Downloading $VANILLA_VERSION server..."
+  log "Downloading $VERSION server..."
   debug "Downloading server from $serverDownloadUrl"
   get -o "$SERVER" "$serverDownloadUrl"
   result=$?

scripts/start-finalExec

@@ -220,6 +220,14 @@ function copyFilesForCurseForge() {
   cp -f /data/eula.txt "${FTB_DIR}/"
 }
 
+if versionLessThan 1.7; then
+  echo "
+MC_HEALTH_EXTRA_ARGS=(
+  --use-server-list-ping
+)
+  " > /data/.mc-health.env
+fi
+
 mcServerRunnerArgs=(
 --stop-duration "${STOP_DURATION:-60}s"
 --named-pipe "${CONSOLE_IN_NAMED_PIPE:-/tmp/minecraft-console-in}"

scripts/start-setupForgeApiMods

@@ -57,7 +57,7 @@ updateReleaseNumber(){
 }
 
 retrieveVersionTypeNumber(){
-  VERSION_NAME="Minecraft ${MAJOR_VANILLA_VERSION}"
+  VERSION_NAME=$(get_major_version "$VERSION")
   minecraft_types=$(curl -X GET -s \
     "${FORGEAPI_BASE_URL}/games/${MINECRAFT_GAME_ID}/version-types" \
     -H 'Accept: application/json' -H 'x-api-key: '${MODS_FORGEAPI_KEY}'')

scripts/start-setupModpack

@@ -3,7 +3,12 @@
 set -e -o pipefail
 
 : "${REMOVE_OLD_MODS:=false}"
+: "${MODS:=}"
+: "${MODS_OUT_DIR:=/data/mods}"
 : "${MODS_FILE:=}"
+: "${PLUGINS:=}"
+: "${PLUGINS_OUT_DIR:=/data/plugins}"
+: "${PLUGINS_FILE:=}"
 : "${REMOVE_OLD_MODS_DEPTH:=1} "
 : "${REMOVE_OLD_MODS_INCLUDE:=*.jar,*-version.json}"
 sum_file=/data/.generic_pack.sum
@@ -17,8 +22,8 @@ CURSE_URL_BASE=${CURSE_URL_BASE:-https://minecraft.curseforge.com/projects}
 
 # Remove old mods/plugins
 if isTrue "${REMOVE_OLD_MODS}" && [ -z "${MODS_FILE}" ]; then
-  removeOldMods /data/mods
-  removeOldMods /data/plugins
+  removeOldMods "$MODS_OUT_DIR"
+  removeOldMods "$PLUGINS_OUT_DIR"
   rm -f "$sum_file"
 fi
 
@@ -41,7 +46,7 @@ function handlePackwiz() {
   fi
 }
 
-function handleModpackListOrFile() {
+function handleModpackZip() {
 # If supplied with a URL for a modpack (simple zip of jars), download it and unpack
 if [[ "$MODPACK" ]]; then
   if isURL "${MODPACK}"; then
@@ -61,83 +66,83 @@ if [[ "$MODPACK" ]]; then
   fi
 
   if [ "$FAMILY" = "SPIGOT" ]; then
-    mkdir -p /data/plugins
-    if ! unzip -o -d /data/plugins /tmp/modpack.zip; then
+    mkdir -p "$PLUGINS_OUT_DIR"
+    if ! unzip -o -d "$PLUGINS_OUT_DIR" /tmp/modpack.zip; then
       log "ERROR: failed to unzip the modpack from ${MODPACK}"
     fi
   else
-    mkdir -p /data/mods
-    if ! unzip -o -d /data/mods /tmp/modpack.zip; then
+    mkdir -p "$MODS_OUT_DIR"
+    if ! unzip -o -d "$MODS_OUT_DIR" /tmp/modpack.zip; then
       log "ERROR: failed to unzip the modpack from ${MODPACK}"
     fi
   fi
   rm -f /tmp/modpack.zip
-
-elif [[ "$MODS" ]]; then
-  if [ "$FAMILY" = "SPIGOT" ]; then
-    out_dir=/data/plugins
-  else
-    out_dir=/data/mods
-  fi
-  mkdir -p "$out_dir"
-
-  for i in ${MODS//,/ }
-  do
-    if isURL "$i"; then
-      log "Downloading mod/plugin $i ..."
-      if ! get --skip-up-to-date -o "${out_dir}" "$i"; then
-        log "ERROR: failed to download from $i into $out_dir"
-        exit 2
-      fi
-    elif [[ -f "$i" && "$i" =~ .*\.jar ]]; then
-      log "Copying plugin located at $i ..."
-      out_file=$(basename "$i")
-      if ! cp "$i" "${out_dir}/$out_file"; then
-        log "ERROR: failed to copy from $i into $out_dir"
-        exit 2
-      fi
-    elif [[ -d "$i" ]]; then
-      log "Copying plugin jars from $i ..."
-      cp "$i"/*.jar "${out_dir}"
-    else
-      log "ERROR Invalid URL or path given in MODS: $i"
-      exit 2
-    fi
-  done
-
-elif [[ "$MODS_FILE" ]]; then
-  if [ ! -f "$MODS_FILE" ]; then
-    log "ERROR: given MODS_FILE file does not exist"
-    exit 2
-  fi
-
-  if [ "$FAMILY" = "SPIGOT" ]; then
-    out_dir=/data/plugins
-  else
-    out_dir=/data/mods
-  fi
-  mkdir -p "$out_dir"
-
-  args=(
-    -o "${out_dir}"
-    --log-progress-each
-    --skip-up-to-date
-    --uris-file "${MODS_FILE}"
-  )
-  if isTrue "${REMOVE_OLD_MODS}"; then
-    args+=(
-    --prune-others "${REMOVE_OLD_MODS_INCLUDE}"
-    --prune-depth "${REMOVE_OLD_MODS_DEPTH}"
-    )
-  fi
-
-  if ! get "${args[@]}" ; then
-    log "ERROR: failed to retrieve one or more mods"
-    exit 1
-  fi
 fi
 }
 
+function handleListings() {
+  if usesMods && usesPlugins; then
+      if [[ "$MODS" ]]; then
+        mkdir -p "$MODS_OUT_DIR"
+        mc-image-helper mcopy \
+          --glob=*.jar \
+          --scope=var-list \
+          --to="$MODS_OUT_DIR" \
+          "$MODS"
+      fi
+      if [[ "$PLUGINS" ]]; then
+        mkdir -p "$PLUGINS_OUT_DIR"
+        mc-image-helper mcopy \
+          --glob=*.jar \
+          --scope=var-list \
+          --to="$PLUGINS_OUT_DIR" \
+          "$PLUGINS"
+      fi
+
+      if [[ "$MODS_FILE" ]]; then
+        mkdir -p "$MODS_OUT_DIR"
+        mc-image-helper mcopy \
+          --file-is-listing \
+          --scope=file-list \
+          --to="$MODS_OUT_DIR" \
+          "$MODS_FILE"
+      fi
+      if [[ "$PLUGINS_FILE" ]]; then
+        mkdir -p "$PLUGINS_OUT_DIR"
+        mc-image-helper mcopy \
+          --file-is-listing \
+          --scope=file-list \
+          --to="$PLUGINS_OUT_DIR" \
+          "$PLUGINS_FILE"
+      fi
+
+  elif usesPlugins || usesMods; then
+    outDir="$MODS_OUT_DIR"
+    if usesPlugins; then
+      outDir="$PLUGINS_OUT_DIR"
+    fi
+
+    if [[ "$MODS" || "$PLUGINS" ]]; then
+      mkdir -p "$outDir"
+      mc-image-helper mcopy \
+        --glob=*.jar \
+        --scope=var-list \
+        --to="$outDir" \
+        "$MODS" "$PLUGINS"
+    fi
+
+    if [[ "$MODS_FILE" || "$PLUGINS_FILE" ]]; then
+      mkdir -p "$outDir"
+      mc-image-helper mcopy \
+        --file-is-listing \
+        --scope=file-list \
+        --to="$outDir" \
+        "$MODS_FILE" "$PLUGINS_FILE"
+    fi
+
+  fi
+}
+
 function handleCurseForgeManifest() {
 if [[ "$MANIFEST" ]]; then
     if [[ -e "$MANIFEST" ]]; then
@@ -284,7 +289,7 @@ function handleModrinthProjects() {
     mc-image-helper modrinth \
       --output-directory=/data \
       --projects="${MODRINTH_PROJECTS}" \
-      --game-version="${VANILLA_VERSION}" \
+      --game-version="${VERSION}" \
       --loader="$loader" \
       --download-optional-dependencies="$MODRINTH_DOWNLOAD_OPTIONAL_DEPENDENCIES" \
       --allowed-version-type="$MODRINTH_ALLOWED_VERSION_TYPE"
@@ -293,7 +298,9 @@ function handleModrinthProjects() {
 
 handlePackwiz
 
-handleModpackListOrFile
+handleModpackZip
+
+handleListings
 
 handleCurseForgeManifest
 

scripts/start-setupMounts

@@ -10,6 +10,8 @@
 : "${REPLACE_ENV_VARIABLES_EXCLUDES:=}"
 : "${REPLACE_ENV_VARIABLES_EXCLUDE_PATHS:=}"
 : "${DEBUG:=false}"
+: "${MODS_OUT_DIR:=/data/mods}"
+: "${PLUGINS_OUT_DIR:=/data/plugins}"
 
 set -e
 isDebugging && set -x
@@ -25,29 +27,24 @@ else
 fi
 
 : "${COPY_PLUGINS_SRC:="/plugins"}"
-: "${COPY_PLUGINS_DEST:="/data/plugins"}"
+: "${COPY_PLUGINS_DEST:=${PLUGINS_OUT_DIR}}"
 
-if [ -d "${COPY_PLUGINS_SRC}" ]; then
-  case ${FAMILY} in
-    SPIGOT|HYBRID)
-      mkdir -p "${COPY_PLUGINS_DEST}"
-      log "Copying any plugins from ${COPY_PLUGINS_SRC} to ${COPY_PLUGINS_DEST}"
-      mc-image-helper \
-        ${subcommand} $updateArg \
-        --replace-env-file-suffixes="${REPLACE_ENV_SUFFIXES}" \
-        --replace-env-excludes="${REPLACE_ENV_VARIABLES_EXCLUDES}" \
-        --replace-env-exclude-paths="${REPLACE_ENV_VARIABLES_EXCLUDE_PATHS}" \
-        --replace-env-prefix="${REPLACE_ENV_VARIABLE_PREFIX}" \
-        "${COPY_PLUGINS_SRC}" "${COPY_PLUGINS_DEST}"
-      ;;
-  esac
+if usesPlugins && [ -d "${COPY_PLUGINS_SRC}" ]; then
+  mkdir -p "${COPY_PLUGINS_DEST}"
+  log "Copying any plugins from ${COPY_PLUGINS_SRC} to ${COPY_PLUGINS_DEST}"
+  mc-image-helper \
+    ${subcommand} $updateArg \
+    --replace-env-file-suffixes="${REPLACE_ENV_SUFFIXES}" \
+    --replace-env-excludes="${REPLACE_ENV_VARIABLES_EXCLUDES}" \
+    --replace-env-exclude-paths="${REPLACE_ENV_VARIABLES_EXCLUDE_PATHS}" \
+    --replace-env-prefix="${REPLACE_ENV_VARIABLE_PREFIX}" \
+    "${COPY_PLUGINS_SRC}" "${COPY_PLUGINS_DEST}"
 fi
 
-# If any modules have been provided, copy them over
 : "${COPY_MODS_SRC:="/mods"}"
-: "${COPY_MODS_DEST:="/data/mods"}"
+: "${COPY_MODS_DEST:=${MODS_OUT_DIR}}"
 
-if [ -d "${COPY_MODS_SRC}" ]; then
+if usesMods && [ -d "${COPY_MODS_SRC}" ]; then
   log "Copying any mods from ${COPY_MODS_SRC} to ${COPY_MODS_DEST}"
   mc-image-helper \
     ${subcommand} $updateArg \

scripts/start-utils

@@ -163,7 +163,7 @@ function normalizeMemSize() {
 
 function versionLessThan() {
   # Use if-else since strict mode might be enabled
-  if mc-image-helper compare-versions "${VANILLA_VERSION}" lt "${1?}"; then
+  if mc-image-helper compare-versions "${VERSION}" lt "${1?}"; then
     return 0
   else
     return 1
@@ -305,3 +305,43 @@ function checkSum() {
     return 1
   fi
 }
+
+function usesMods() {
+  case "$FAMILY" in
+    FORGE|FABRIC|HYBRID|SPONGE)
+      return 0
+  esac
+  return 1
+}
+
+function usesPlugins() {
+  case "$FAMILY" in
+    SPIGOT|HYBRID)
+      return 0
+  esac
+  return 1
+}
+
+function resolveVersion() {
+  givenVersion="$VERSION"
+  # shellcheck disable=SC2153
+  if ! VERSION=$(mc-image-helper resolve-minecraft-version "$VERSION"); then
+    exit 2
+  fi
+  log "Resolved version given ${givenVersion} into ${VERSION}"
+}
+
+function resolveFamily() {
+  case "$TYPE" in
+    PAPER|SPIGOT|BUKKIT|CANYON|PUFFERFISH|PURPUR)
+      FAMILY=SIGOT
+      ;;
+    FORGE)
+      FAMILY=FORGE
+      ;;
+    FABRIC|QUILT)
+      FAMILY=FABRIC
+      ;;
+  esac
+  export FAMILY
+}

tests/setuponlytests/auto_curseforge/docker-compose.yml

@@ -6,7 +6,7 @@ services:
     environment:
       EULA: "true"
       SETUP_ONLY: "TRUE"
-      TYPE: AUTO_CURSEFORGE
+      MOD_PLATFORM: AUTO_CURSEFORGE
       CF_API_KEY: ${CF_API_KEY}
       CF_SLUG: the-pixelmon-modpack
       CF_FILENAME_MATCHER: "9.1.2"

tests/setuponlytests/modrinth/docker-compose.yml

@@ -7,10 +7,7 @@ services:
       EULA: "true"
       SETUP_ONLY: "true"
       TYPE: FABRIC
-      FABRIC_LAUNCHER: /servers/fake.jar
-      CUSTOM_SERVER: /servers/fake.jar
       VERSION: 1.19.1
       MODRINTH_PROJECTS: fabric-api,cloth-config
     volumes:
       - ./data:/data
-      - ./fake.jar:/servers/fake.jar