cf: resolve remaining exclude/include slugs after first unknown mod (#3909 )

Put back particle-effects-reforged and flerovium in global excludes (#3906 )
autocf: log warning and proceed if an excluded mod cannot be resolved (#3904 )
2026-02-17 07:03:57 +00:00 · 2026-02-04 06:57:22 -06:00 · 2026-02-03 19:02:36 -06:00 · 2026-02-03 10:13:25 -06:00 · 2026-02-03 08:51:04 -06:00 · 2026-02-03 07:33:06 -06:00
35 changed files with 503 additions and 439 deletions
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -12,7 +12,11 @@ on:
      - "examples/**"
      - "notes/**"
      - "kustomize/**"
+      - "docker-compose.yml"
      - "images.json"
+      - "compose-docs.yml"
+      - "zensical.toml"
+      - ".readthedocs.yaml"

 jobs:
  build:
@@ -23,17 +27,13 @@ jobs:
        variant:
          - java25
          - java25-jdk
-          - java25-graalvm
          - java21
          - java21-alpine
-          - java21-graalvm
          - java21-jdk
          - java17
-          - java17-graalvm
          - java16
          - java11
          - java8
-          - java8-graalvm-ce
          - java8-jdk
        include:
        # JAVA 25
@@ -45,15 +45,7 @@ jobs:
            baseImage: eclipse-temurin:25
            platforms: linux/amd64,linux/arm64
            mcVersion: latest
-          - variant: java25-graalvm
-            baseImage: container-registry.oracle.com/graalvm/jdk:25-ol10
-            platforms: linux/amd64,linux/arm64
-            mcVersion: latest
        # JAVA 21:
-          - variant: java21-graalvm
-            baseImage: container-registry.oracle.com/graalvm/jdk:21-ol10
-            platforms: linux/amd64,linux/arm64
-            mcVersion: latest
          - variant: java21
            baseImage: eclipse-temurin:21-jre
            platforms: linux/amd64,linux/arm64
@@ -72,10 +64,6 @@ jobs:
            baseImage: eclipse-temurin:17-jre-focal
            platforms: linux/amd64,linux/arm/v7,linux/arm64
            mcVersion: 1.20.4
-          - variant: java17-graalvm
-            baseImage: container-registry.oracle.com/graalvm/jdk:17-ol10
-            platforms: linux/amd64,linux/arm64
-            mcVersion: 1.20.4
        # JAVA 16
          - variant: java16
            baseImage: adoptopenjdk:16-jre-hotspot
@@ -93,12 +81,6 @@ jobs:
            mcVersion: 1.12.2
            # Pin version for Java 8
            mcHelperVersion: 1.51.1
-          - variant: java8-graalvm-ce
-            baseImage: ghcr.io/graalvm/graalvm-ce:java8
-            platforms: linux/amd64
-            mcVersion: 1.12.2
-            # Pin version for Java 8
-            mcHelperVersion: 1.51.1
          - variant: java8-jdk
            baseImage: eclipse-temurin:8u312-b07-jdk-focal
            platforms: linux/amd64,linux/arm64
@@ -108,11 +90,11 @@ 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: java21
+      MAIN_VARIANT: java25
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
-        uses: actions/checkout@v6.0.1
+        uses: actions/checkout@v6.0.2
        with:
          # for build-files step
          fetch-depth: 0
@@ -175,18 +157,19 @@ jobs:
          MINECRAFT_VERSION: ${{ matrix.mcVersion }}
          VARIANT: ${{ matrix.variant }}
          CF_API_KEY: ${{ secrets.CF_API_KEY }}
+          GH_TOKEN: ${{ github.token }}
        run: |
          tests/test.sh

      - name: Login to DockerHub
-        uses: docker/login-action@v3.6.0
+        uses: docker/login-action@v3.7.0
        if: env.HAS_IMAGE_REPO_ACCESS
        with:
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Login to GHCR
-        uses: docker/login-action@v3.6.0
+        uses: docker/login-action@v3.7.0
        if: env.HAS_IMAGE_REPO_ACCESS
        with:
          registry: ghcr.io
--- a/.github/workflows/verify-pr.yml
+++ b/.github/workflows/verify-pr.yml
@@ -9,9 +9,11 @@ on:
      - "examples/**"
      - "notes/**"
      - "kustomize/**"
-      - "docker-compose*.yml"
-      - "mkdocs.yml"
+      - "docker-compose.yml"
      - "images.json"
+      - "compose-docs.yml"
+      - "zensical.toml"
+      - ".readthedocs.yaml"

 jobs:
  build:
@@ -19,14 +21,14 @@ jobs:
      fail-fast: false
      matrix:
        variant:
-          - java21
+          - java25
          - java21-alpine
          - java17
          - java8
        include:
-        # JAVA 21:
-          - variant: java21
-            baseImage: eclipse-temurin:21-jre
+        # JAVA 21/25:
+          - variant: java25
+            baseImage: eclipse-temurin:25-jre
            platforms: linux/amd64,linux/arm64
            mcVersion: latest
          - variant: java21-alpine
@@ -50,7 +52,7 @@ jobs:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
-        uses: actions/checkout@v6.0.1
+        uses: actions/checkout@v6.0.2
        with:
          # for build-files step
          fetch-depth: 0
@@ -92,5 +94,6 @@ jobs:
          VARIANT: ${{ matrix.variant }}
          CF_API_KEY: ${{ secrets.CF_API_KEY }}
          DEBUG: ${{ runner.debug }}
+          GH_TOKEN: ${{ github.token }}
        run: |
          tests/test.sh
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@
 *.iml
 /gh-md-toc
 personal-build-and-develop.*
+site/
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -1,14 +1,22 @@
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-version: 2
-
-build:
-  os: ubuntu-22.04
-  tools:
-    python: "3.11"
-
-mkdocs:
-  configuration: mkdocs.yml
-
-python:
-  install:
-    - requirements: docs/requirements.txt
+version: 2
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: latest
+  jobs:
+    # We recommend using a requirements file for reproducible builds.
+    # This is just a quick example to get started.
+    # https://docs.readthedocs.io/page/guides/reproducible-builds.html
+    install:
+      - pip install zensical
+    build:
+      html:
+        - zensical build
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive site/* $READTHEDOCS_OUTPUT/html/
--- a/4
+++ b/4
@@ -1,4 +1,4 @@
-ARG BASE_IMAGE=eclipse-temurin:21-jre
+ARG BASE_IMAGE=eclipse-temurin:25-jre
 FROM ${BASE_IMAGE}

 # hook into docker BuildKit --platform support
@@ -49,7 +49,7 @@ RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
  --var version=${MC_SERVER_RUNNER_VERSION} --var app=mc-server-runner --file {{.app}} \
  --from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz

-ARG MC_HELPER_VERSION=1.52.1
+ARG MC_HELPER_VERSION=1.53.2
 ARG MC_HELPER_BASE_URL=${GITHUB_BASEURL}/itzg/mc-image-helper/releases/download/${MC_HELPER_VERSION}
 # used for cache busting local copy of mc-image-helper
 ARG MC_HELPER_REV=1
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 [![Docker Stars](https://img.shields.io/docker/stars/itzg/minecraft-server.svg?logo=docker)](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)
 [![Discord](https://img.shields.io/discord/660567679458869252?label=Discord&logo=discord)](https://discord.gg/DXfKpjB)
-[![Build and Publish](https://github.com/itzg/docker-minecraft-server/actions/workflows/build-multiarch.yml/badge.svg)](https://github.com/itzg/docker-minecraft-server/actions/workflows/build-multiarch.yml)
+[![Build and Publish](https://github.com/itzg/docker-minecraft-server/actions/workflows/build.yml/badge.svg)](https://github.com/itzg/docker-minecraft-server/actions/workflows/build.yml)
 [![](https://img.shields.io/badge/Donate-Buy%20me%20a%20coffee-orange.svg)](https://www.buymeacoffee.com/itzg)
 [![Documentation Status](https://readthedocs.org/projects/docker-minecraft-server/badge/?version=latest)](https://docker-minecraft-server.readthedocs.io/en/latest/?badge=latest)

--- a/build/ol/install-packages.sh
+++ b/build/ol/install-packages.sh
@@ -64,11 +64,16 @@ fi
 # Clean up DNF when done
 dnf clean all

-# Download and install patched knockd
-curl -fsSL -o /tmp/knock.tar.gz https://github.com/Metalcape/knock/releases/download/0.8.1/knock-0.8.1-$TARGET.tar.gz
-tar -xf /tmp/knock.tar.gz -C /usr/local/ && rm /tmp/knock.tar.gz
-ln -s /usr/local/sbin/knockd /usr/sbin/knockd
-setcap cap_net_raw=ep /usr/local/sbin/knockd
+cat <<EOF > /usr/local/sbin/knockd
+#!/bin/sh
+
+echo "Auto-pause (using knockd) is currently unavailable on graalvm image variants"
+echo "Consider using a different image variant https://docker-minecraft-server.readthedocs.io/en/latest/versions/java/"
+echo "or mc-router's auto scale up/down feature https://github.com/itzg/mc-router#docker-auto-scale-updown"
+exit 2
+EOF
+chmod 755 /usr/local/sbin/knockd
+# TODO restore retrieval from https://github.com/Metalcape/knock when tar's "Cannot open: Invalid argument" is solved

 # Set git credentials globally
 cat <<EOF >> /etc/gitconfig
--- a/compose-docs.yml
+++ b/compose-docs.yml
@@ -0,0 +1,16 @@
+# This composition can be used to serve up the rendered mkdocs for local authoring.
+#
+# docker compose -f compose-docs.yml -p zensical up
+#
+# and then access http://localhost:8000
+
+services:
+  zensical:
+    build:
+      context: .
+      dockerfile: docs/Dockerfile
+    volumes:
+      - ./zensical.toml:/docs/zensical.toml
+      - ./docs:/docs/docs
+    ports:
+      - "8000:8000"
--- a/docker-compose-mkdocs.yml
+++ b/docker-compose-mkdocs.yml
@@ -1,19 +0,0 @@
-# This composition can be used to serve up the rendered mkdocs for local authoring.
-#
-# docker compose -f docker-compose-mkdocs.yml -p mkdocs up
-#
-# and then access http://localhost:8000
-
-services:
-  mkdocs:
-    build:
-      context: .
-      dockerfile: docs/Dockerfile
-    volumes:
-      - ./mkdocs.yml:/mkdocs/mkdocs.yml
-      - ./docs:/mkdocs/docs
-    command:
-      - serve
-      - --dev-addr=0.0.0.0:8000
-    ports:
-      - "8000:8000"
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -1,10 +1,4 @@
-FROM python:3.11
-
-RUN pip install --upgrade pip
-
-WORKDIR /mkdocs
+FROM zensical/zensical

 RUN --mount=target=/build/requirements.txt,source=docs/requirements.txt \
    pip install -r /build/requirements.txt
-
-ENTRYPOINT ["mkdocs"]
--- a/docs/configuration/misc-options.md
+++ b/docs/configuration/misc-options.md
@@ -77,9 +77,15 @@ The openj9 image tags include specific variables to simplify configuration:
 - `-e TUNE_NURSERY_SIZES=TRUE` : configures nursery sizes where the initial size is 50%
  of the `MAX_MEMORY` and the max size is 80%.

-## Customizing log4j2 configuration
+## Customize Minecraft server logging

-The image now uses a templated log4j2 configuration based on PaperMC's logging setup, which is automatically applied for versions that don't require Log4j security patches. This configuration provides rolling logs and advanced logging features by default.
+The image can use a templated log4j2 configuration based on PaperMC's logging setup, which is automatically applied for versions that don't require Log4j security patches. This configuration provides rolling logs and advanced logging features by default.
+
+Set the environment variable `GENERATE_LOG4J2_CONFIG` to "true" to enable the following features.
+
+!!! note
+
+    This configures the server logging only. To diagnose container startup, set the `DEBUG` environment variable to "true".

 ### Customization via environment variables

--- a/docs/configuration/server-properties.md
+++ b/docs/configuration/server-properties.md
@@ -1,4 +1,8 @@
-In order to unify management of the Minecraft server container, all of the [`server.properties`](https://minecraft.wiki/w/Server.properties) entries can be managed by the environment variables described in the sections below. Some of the mappings provide additional functionality above and beyond the properties file.
+To unify management of the Minecraft server container, all known [`server.properties`](https://minecraft.wiki/w/Server.properties) entries can be managed by the environment variables described in the sections below. Some mappings provide additional functionality above and beyond the properties file and will be described in the sections below.
+
+!!! warning "Version compatibility"
+
+    Not all server properties are supported by all versions of Minecraft. Since this image supports a wide range of versions, please consult the [server properties documentation](https://minecraft.wiki/w/Server.properties) for the version you are using.

 If you prefer to manually manage the `server.properties` file, set `OVERRIDE_SERVER_PROPERTIES` to "false". Similarly, you can entirely skip the startup script's creation of `server.properties` by setting `SKIP_SERVER_PROPERTIES` to "true".

@@ -238,15 +242,46 @@ By default an existing `server-icon.png` file will not be replaced, that can be

 ### RCON

-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".
+RCON is **enabled by default** to allow for graceful shut down of the server and coordination of save state during backups. RCON can be disabled by setting `ENABLE_RCON` to "false".

 !!! warning

    Disabling RCON will remove and limit some features, such as interactive and color console support.

-The default password is randomly generated on each startup; however, a specific one can be set with `RCON_PASSWORD`.
+#### RCON Password

-**DO NOT MAP THE RCON PORT EXTERNALLY** unless you are aware of all the consequences and have set a **secure password** with `RCON_PASSWORD`. 
+The default password is randomly generated on each startup. However, you can specify a password using one of the following environment variables:
+
+* Set `RCON_PASSWORD` to your desired password.
+* Set `RCON_PASSWORD_FILE` to the path of a file containing the password.
+
+Using `RCON_PASSWORD_FILE` is the recommended method for managing sensitive data, as it allows full support for [Docker Secrets](https://docs.docker.com/compose/how-tos/use-secrets/).
+
+??? example
+    ```yaml title="compose.yaml"
+    services:
+      mc:
+        image: itzg/minecraft-server:latest
+        pull_policy: daily
+        tty: true
+        stdin_open: true
+        ports:
+          - "25565:25565"
+        environment:
+          EULA: "TRUE"
+          RCON_PASSWORD_FILE: /run/secrets/rcon_pass # Points to the path where the secret is mounted
+        volumes:
+          # attach the relative directory 'data' to the container's /data path
+          - ./data:/data
+        secrets:
+          - rcon_pass
+    
+    secrets:
+      rcon_pass:
+        file: ./rcon_password # local file containing the password
+    ```
+!!! warning
+    **BE CAUTIOUS OF MAPPING THE RCON PORT EXTERNALLY** unless you are aware of all the consequences and have set a **secure password**.

 !!! info 

@@ -396,11 +431,16 @@ When using `docker run` from a bash shell, the entries must be quoted with the `

 ### Other server property mappings

+!!! warning "Version compatibility"
+
+    Not all server properties are supported by all versions of Minecraft. Since this image supports a wide range of versions, please consult the [server properties documentation](https://minecraft.wiki/w/Server.properties) for the version you are using.
+
 | Environment Variable                    | Server Property                                                                                                               |
 |-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
 | ACCEPTS_TRANSFERS                       | [accepts-transfers](https://minecraft.wiki/w/Server.properties#accepts-transfers)                                             |
 | ALLOW_FLIGHT                            | [allow-flight](https://minecraft.wiki/w/Server.properties#allow-flight)                                                       |
 | ALLOW_NETHER                            | [allow-nether](https://minecraft.wiki/w/Server.properties#allow-nether)                                                       |
+| ANNOUNCE_PLAYER_ACHIEVEMENTS            | [announce-player-achievements](https://minecraft.wiki/w/Server.properties#announce-player-achievements)                       |
 | BROADCAST_CONSOLE_TO_OPS                | [broadcast-console-to-ops](https://minecraft.wiki/w/Server.properties#broadcast-console-to-ops)                               |
 | BROADCAST_RCON_TO_OPS                   | [broadcast-rcon-to-ops](https://minecraft.wiki/w/Server.properties#broadcast-rcon-to-ops)                                     |
 | BUG_REPORT_LINK                         | [bug-report-link](https://minecraft.wiki/w/Server.properties#bug-report-link)                                                 |
@@ -411,6 +451,7 @@ When using `docker run` from a bash shell, the entries must be quoted with the `
 | FORCE_GAMEMODE                          | [force-gamemode](https://minecraft.wiki/w/Server.properties#force-gamemode)                                                   |
 | FUNCTION_PERMISSION_LEVEL               | [function-permission-level](https://minecraft.wiki/w/Server.properties#function-permission-level)                             |
 | GENERATE_STRUCTURES                     | [generate-structures](https://minecraft.wiki/w/Server.properties#generate-structures)                                         |
+| GENERATOR_SETTINGS                      | [generator-settings](https://minecraft.wiki/w/Server.properties#generator-settings)                                           |                                                                                                                    
 | HARDCORE                                | [hardcore](https://minecraft.wiki/w/Server.properties#hardcore)                                                               |
 | HIDE_ONLINE_PLAYERS                     | [hide-online-players](https://minecraft.wiki/w/Server.properties#hide-online-players)                                         |
 | LOG_IPS                                 | [log-ips](https://minecraft.wiki/w/Server.properties#log-ips)                                                                 |
@@ -422,6 +463,12 @@ When using `docker run` from a bash shell, the entries must be quoted with the `
 | MANAGEMENT_SERVER_TLS_ENABLED           | [management-server-tls-enabled](https://minecraft.wiki/w/Server.properties#management-server-tls-enabled)                     |
 | MANAGEMENT_SERVER_TLS_KEYSTORE          | [management-server-tls-keystore](https://minecraft.wiki/w/Server.properties#management-server-tls-keystore)                   |
 | MANAGEMENT_SERVER_TLS_KEYSTORE_PASSWORD | [management-server-tls-keystore-password](https://minecraft.wiki/w/Server.properties#management-server-tls-keystore-password) |
+| MAX_BUILD_HEIGHT                        | [max-build-height](https://minecraft.wiki/w/Server.properties#max-build-height)                                               |
+| MAX_COMMAND_CHAIN_LENGTH                | [max-command-chain-length](https://minecraft.wiki/w/Server.properties#max-command-chain-length)                               |
+| MAX_ENTITY_CRAMMING                     | [max-entity-cramming](https://minecraft.wiki/w/Server.properties#max-entity-cramming)                                         |
+| MAX_ENTITY_COLLISION_RADIUS             | [max-entity-collision-radius](https://minecraft.wiki/w/Server.properties#max-entity-collision-radius)                         |
+| MAX_FUNCTION_CHAIN_DEPTH                | [max-function-chain-depth](https://minecraft.wiki/w/Server.properties#max-function-chain-depth)                               |
+| MAX_NEIGHBORS                           | [max-neighbors](https://minecraft.wiki/w/Server.properties#max-neighbors)                                                     |
 | MAX_CHAINED_NEIGHBOR_UPDATES            | [max-chained-neighbor-updates](https://minecraft.wiki/w/Server.properties#max-chained-neighbor-updates)                       |
 | MAX_PLAYERS                             | [max-players](https://minecraft.wiki/w/Server.properties#max-players)                                                         |
 | MAX_TICK_TIME                           | [max-tick-time](https://minecraft.wiki/w/Server.properties#max-tick-time)                                                     |
@@ -439,9 +486,12 @@ When using `docker run` from a bash shell, the entries must be quoted with the `
 | RESOURCE_PACK_PROMPT                    | [resource-pack-prompt](https://minecraft.wiki/w/Server.properties#resource-pack-prompt)                                       |
 | SERVER_NAME                             | [server-name](https://minecraft.wiki/w/Server.properties#server-name)                                                         |
 | SIMULATION_DISTANCE                     | [simulation-distance](https://minecraft.wiki/w/Server.properties#simulation-distance)                                         |
+| SNOOPER_ENABLED                         | [snooper-enabled](https://minecraft.wiki/w/Server.properties#snooper-enabled)                                                 |
+| SPAWN_ANIMALS                           | [spawn-animals](https://minecraft.wiki/w/Server.properties#spawn-animals)                                                     |
 | SPAWN_MONSTERS                          | [spawn-monsters](https://minecraft.wiki/w/Server.properties#spawn-monsters)                                                   |
+| SPAWN_NPCS                              | [spawn-npcs](https://minecraft.wiki/w/Server.properties#spawn-npcs)                                                           |
 | SPAWN_PROTECTION                        | [spawn-protection](https://minecraft.wiki/w/Server.properties#spawn-protection)                                               |
 | STATUS_HEARTBEAT_INTERVAL               | [status-heartbeat-interval](https://minecraft.wiki/w/Server.properties#status-heartbeat-interval)                             |
 | SYNC_CHUNK_WRITES                       | [sync-chunk-writes](https://minecraft.wiki/w/Server.properties#sync-chunk-writes)                                             |
 | USE_NATIVE_TRANSPORT                    | [use-native-transport](https://minecraft.wiki/w/Server.properties#use-native-transport)                                       |
-| VIEW_DISTANCE                           | [view-distance](https://minecraft.wiki/w/Server.properties#view-distance)                                                     |
+| VIEW_DISTANCE                           | [view-distance](https://minecraft.wiki/w/Server.properties#view-distance)                                                     |
--- a/docs/misc/autoscale/autoscale.md
+++ b/docs/misc/autoscale/autoscale.md
@@ -0,0 +1,39 @@
+
+# Autoscaling (sleep when idle)
+
+Autoscaling (sometimes called *sleeping*, *scale to zero* or *wake on join*) is the pattern of stopping a Minecraft server when nobody is playing and starting it again when someone tries to connect with the intention of saving resources when the server is not in use (e.g., on a VPS with limited CPU/RAM or a home server).
+
+## mc-router
+
+[mc-router](https://github.com/itzg/mc-router) is a Minecraft-aware router/multiplexer.
+
+- Routes players by the hostname they connect with (useful for multiple servers behind one port)
+- Can auto-start a backend container on join and stop it again after an idle timeout
+
+Examples:
+
+- See the mc-router section in [Examples](../examples.md#mc-router-with-auto-scale)
+
+## Lazymc
+
+[Lazymc](https://github.com/timvisee/lazymc) can keep a server “asleep” until a player connects. With Docker it’s commonly used via [lazymc-docker-proxy](https://github.com/joesturge/lazymc-docker-proxy).
+
+- Players connect to the proxy; the proxy starts/stops the server container
+- Usually requires a static IP for the Minecraft container on a user-defined network
+
+Example:
+
+- See the Lazymc section in [Examples](../examples.md#lazymc-put-your-minecraft-server-to-rest-when-idle)
+
+## Lazytainer
+
+[Lazytainer](https://github.com/vmorganp/Lazytainer) starts/stops containers based on network traffic.
+
+- Uses packet thresholds + inactivity timeouts (not Minecraft hostname aware)
+- Can be triggered by port scans/pings in noisy environments
+
+Example:
+
+- See the Lazytainer section in [Examples](../examples.md#lazytainer-stop-minecraft-container-based-on-traffic)
+
+
--- a/docs/misc/contributing/docs.md
+++ b/docs/misc/contributing/docs.md
@@ -1,6 +1,6 @@
 # Site documentation

-The documentation for this image/repository is written in markdown and built by [MkDocs](https://www.mkdocs.org/) into a documentation website hosted at [Read the Docs](https://readthedocs.org/). [Here is general information about writing MkDocs markdown](https://www.mkdocs.org/user-guide/writing-your-docs/) and [specifics for the Material theme used](https://squidfunk.github.io/mkdocs-material/reference/).
+The documentation for this image/repository is written in markdown and built using [Zensical](https://zensical.org/) into a documentation website hosted at [Read the Docs](https://readthedocs.org/). [Here is general information about writing Zensical markdown](https://zensical.org/docs/authoring/markdown/).

 !!! note
    The README.md rarely needs to be modified and only serves as a brief introduction to the project.
@@ -10,7 +10,7 @@ The documentation source is maintained in the [docs](https://github.com/itzg/doc
 It will be very helpful to view the rendered documentation as you're editing. To do that run the following from the top-level directory:

 ```shell
-docker compose -f docker-compose-mkdocs.yml -p mkdocs up
+docker compose -f compose-docs.yml -p zensical up
 ```

-You can access the live documentation rendering at <http://localhost:8000>.
+You can access the live documentation rendering at <http://localhost:8000>.
--- a/docs/misc/examples.md
+++ b/docs/misc/examples.md
@@ -27,6 +27,48 @@ services:

 [Source](https://github.com/itzg/docker-minecraft-server/blob/master/examples/geyser/docker-compose.yml)

+
+## mc-router with auto-scale
+
+Using [mc-router](https://github.com/itzg/mc-router) in front of one or multiple Minecraft server containers allows you to route players based on the hostname they use to connect.
+
+With `AUTO_SCALE_UP` and `AUTO_SCALE_DOWN` enabled, mc-router can automatically start a target server when a player connects and stop it again after a period of inactivity.
+
+```yaml title="compose.yaml"
+services:
+  router:
+    image: itzg/mc-router
+    environment:
+      IN_DOCKER: true
+      AUTO_SCALE_DOWN: true
+      AUTO_SCALE_UP: true
+      AUTO_SCALE_DOWN_AFTER: 2h
+      AUTO_SCALE_ASLEEP_MOTD: "Server is asleep. Join again to wake it up!"
+    ports:
+      - "25565:25565"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+
+  vanilla:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "TRUE"
+    labels:
+      mc-router.host: "vanilla.example.com"
+
+  paper:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "TRUE"
+      TYPE: PAPER
+    labels:
+      mc-router.host: "paper.example.com"
+```
+
+[Source](https://github.com/itzg/mc-router/blob/main/examples/docker-autoscale/compose-minimal.yml)
+
+[More detailed example](https://github.com/itzg/mc-router/blob/main/examples/docker-autoscale/compose.yml)
+
 ## Lazymc - Put your Minecraft server to rest when idle

 With [lazymc-docker-proxy](https://github.com/joesturge/lazymc-docker-proxy) you are able to use [lazymc](https://github.com/timvisee/lazymc) with the minecraft container.
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,10 +1,25 @@
-mkdocs-material == 9.7.0
-mkdocs-autorefs == 1.4.3
-mkdocstrings[python] == 0.30.1
-mkdocs-literate-nav == 0.6.2
-mdx-gh-links == 0.4
-# need to pin for auto reload to work
-# see https://github.com/mkdocs/mkdocs/issues/4032
-click==8.2.1
-mkdocs-click == 0.9.0
-mkdocs-static-i18n == 1.3.0
+click==8.3.1
+colorama==0.4.6
+deepmerge==2.0
+ghp-import==2.1.0
+griffe==1.15.0
+Jinja2==3.1.6
+Markdown==3.10.1
+MarkupSafe==3.0.3
+mergedeep==1.3.4
+mkdocs==1.6.1
+mkdocs-autorefs==1.4.3
+mkdocs-get-deps==0.2.0
+mkdocstrings==1.0.2
+mkdocstrings-python==2.0.1
+packaging==26.0
+pathspec==1.0.4
+platformdirs==4.5.1
+Pygments==2.19.2
+pymdown-extensions==10.20.1
+python-dateutil==2.9.0.post0
+PyYAML==6.0.3
+pyyaml_env_tag==1.1
+six==1.17.0
+watchdog==6.0.0
+# zensical @ file:///
--- a/docs/sending-commands/ssh.md
+++ b/docs/sending-commands/ssh.md
@@ -0,0 +1,70 @@
+---
+title: Over SSH
+---
+
+The container can host an SSH console. It is enabled by setting `ENABLE_SSH` to `true`.
+The SSH server only supports password based authentication. The password is the same as the RCON password.
+
+!!! question
+    See [the RCON password](../configuration/server-properties.md/#rcon-password) section under configuration/server-properties for more information on how to set an RCON password.
+
+The SSH server runs on port `2222` inside the container.
+
+??? tip "Tip: Exposing the SSH port"
+
+    !!! warning "Security Implications"
+        By default, publishing ports in Docker binds them to all network interfaces (`0.0.0.0`), making the SSH console accessible to any device that can reach your host machine.
+        
+        Since the SSH console grants **full administrative access** to your server, it is critical to use a strong [RCON password](../configuration/server-properties.md/#rcon-password). 
+        
+        If you wish to restrict access to the local machine only, refer to the [Docker documentation](https://docs.docker.com/engine/network/port-publishing/#publishing-ports) on binding to specific IP addresses (e.g., `127.0.0.1:2222:2222`).
+      
+        If SSH access is only intended for inter-container connections, consider **NOT** forwarding the port to the host machine, and putting the containers in a shared [Docker network](https://docs.docker.com/engine/network/#user-defined-networks).
+
+    ```yaml title="compose.yaml"
+    services:
+      mc:
+        ports:
+          - '25565:25565'
+          - '2222:2222'
+    ```
+
+## Connecting
+
+Connecting should be as simple as running
+```bash
+ssh anyuser@127.0.0.1 -p 2222
+```
+and typing in the RCON password.
+
+## Environment variables
+
+| Environment Variable | Usage                     | Default |
+| -------------------- | ------------------------- | ------- |
+| `ENABLE_SSH`   | Enable remote SSH console | `false` |
+
+
+## Example
+
+```yaml title="compose.yaml"
+services:
+  mc:
+    image: itzg/minecraft-server:latest
+    pull_policy: daily
+    tty: true
+    stdin_open: true
+    ports:
+      - "25565:25565"
+      - "2222:2222"
+    environment:
+      EULA: "TRUE"
+      ENABLE_SSH: true
+      RCON_PASSWORD_FILE: /run/secrets/rcon_pass
+    volumes:
+      # attach the relative directory 'data' to the container's /data path
+      - ./data:/data
+    
+secrets:
+  rcon_pass:
+    file: ./rcon_password
+```
--- a/docs/sending-commands/websocket.md
+++ b/docs/sending-commands/websocket.md
@@ -1,8 +1,8 @@
 ---
-title: With websocket
+title: With WebSocket
 ---

-With `WEBSOCKET_CONSOLE` set to `true`, logs can be streamed, and commands sent, over a websocket connection.
+With `WEBSOCKET_CONSOLE` set to `true`, logs can be streamed, and commands sent, over a WebSocket connection.
 The API is available on `/console`.

 ## Password
@@ -21,7 +21,16 @@ The listen address and port can be set with `WEBSOCKET_ADDRESS` (defaults to `0.
 ## Log history
 When a connection is established, the last 50 (by default, configurable with `WEBSOCKET_LOG_BUFFER_SIZE`) log lines are sent with a `logHistory` type message.

-??? tip "Tip: Remember to forward the websocket port on the host"
+??? tip "Tip: Remember to forward the WebSocket port on the host"
+
+    !!! warning "Security Implications"
+        By default, publishing ports in Docker binds them to all network interfaces (`0.0.0.0`), making the WebSocket console accessible to any device that can reach your host machine.
+        
+        Since the WebSocket console grants **full administrative access** to your server, it is critical to use a strong [WebSocket password](#password) or [RCON password](../configuration/server-properties.md/#rcon-password).
+      
+        If you wish to restrict access to the local machine only, refer to the [Docker documentation](https://docs.docker.com/engine/network/port-publishing/#publishing-ports) on binding to specific IP addresses (e.g., `127.0.0.1:80:80`).
+        
+        If WebSocket access is only intended for inter-container connections, consider **NOT** forwarding the port to the host machine, and putting the containers in a shared [Docker network](https://docs.docker.com/engine/network/#user-defined-networks).

    ```yaml title="compose.yaml"
    services:
@@ -34,12 +43,12 @@ When a connection is established, the last 50 (by default, configurable with `WE
 ## Environment variables
 | Environment Variable               | Usage                                                      | Default      |
 | ---------------------------------- | ---------------------------------------------------------- | ------------ |
-| `WEBSOCKET_CONSOLE`                | Allow remote shell over websocket                          | `false`      |
-| `WEBSOCKET_ADDRESS`                | Bind address for websocket server                          | `0.0.0.0:80` |
+| `WEBSOCKET_CONSOLE`                | Allow remote shell over WebSocket                          | `false`      |
+| `WEBSOCKET_ADDRESS`                | Bind address for WebSocket server                          | `0.0.0.0:80` |
 | `WEBSOCKET_DISABLE_ORIGIN_CHECK`   | Disable checking if origin is trusted                      | `false`      |
 | `WEBSOCKET_ALLOWED_ORIGINS`        | Comma-separated list of trusted origins                    | ` `          |
 | `WEBSOCKET_PASSWORD`               | Password will be the same as RCON_PASSWORD if unset        | ` `          |
-| `WEBSOCKET_DISABLE_AUTHENTICATION` | Disable websocket authentication                           | `false`      |
+| `WEBSOCKET_DISABLE_AUTHENTICATION` | Disable WebSocket authentication                           | `false`      |
 | `WEBSOCKET_LOG_BUFFER_SIZE`        | Number of log lines to save and send to connecting clients | `50`         |

 ## API Schema
--- a/docs/types-and-platforms/mod-platforms/gtnh.md
+++ b/docs/types-and-platforms/mod-platforms/gtnh.md
@@ -12,11 +12,11 @@ Configuration options with defaults:

 ## Set Modpack version

-As GTNH is a Minecraft 1.7.10 modpack, when using it your minecraft version is set to 1.7.10 by default. The [modpack version](https://www.gtnewhorizons.com/downloads/) can be selected by setting `GTNH_PACK_VERSION` to `latest`, `latest-dev` or any specific version number. `latest` will automatically select the latest full release version available and deploy the server with it (Note: this will also automatically update the server on startup). `latest-dev` does the same but selects the latest version marked as beta or RC (it wont select a full release version even if a newer exist). The third (and recommended) option is setting the server to a specific version like `2.8.1` to manage updates manually.
+As GTNH is a Minecraft 1.7.10 modpack, when using it your minecraft version is set to 1.7.10 by default. The [modpack version](https://www.gtnewhorizons.com/downloads/) can be selected by setting `GTNH_PACK_VERSION` to `latest`, `latest-dev` or any specific version number. `latest` will automatically select the latest full release version available and deploy the server with it (Note: this will also automatically update the server on startup). `latest-dev` does the same but selects the latest version marked as beta or RC (it won't select a full release version even if a newer exist). The third (and recommended) option is setting the server to a specific version like `2.8.1` to manage updates manually.

 > To actively prevent an update from happening you can set the environment variable `SKIP_GTNH_UPDATE_CHECK` to true this will prevent any update check from running, but will also prevent the server install from running, so just set it after the initial setup.

-## Ressource requirements
+## Resource requirements

 **Recommended Minimum:**

--- a/docs/variables.md
+++ b/docs/variables.md
@@ -216,102 +216,6 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
            <td><code>FALSE</code></td>
            <td>⬜️</td>
        </tr>
-        <tr>
-            <td><code>MAX_PLAYERS</code></td>
-            <td>The maximum number of players that can join the server.</td>
-            <td><code>20</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>MAX_WORLD_SIZE</code></td>
-            <td>The maximum possible size in blocks, expressed as a radius.</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>ALLOW_NETHER</code></td>
-            <td>Allows players to travel to the Nether</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>ANNOUNCE_PLAYER_ACHIEVEMENTS</code></td>
-            <td>Allows server to announce when a player gets an achievement.</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>ENABLE_COMMAND_BLOCK</code></td>
-            <td>Enables the command blocks.</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>FORCE_GAMEMODE</code></td>
-            <td>Force players to join in the default game mode.</td>
-            <td><code>false</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>GENERATE_STRUCTURES</code></td>
-            <td>Defines whether structures (such as villages) will be generated.</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>HARDCORE</code></td>
-            <td>If set to <code>true</code>, players will be set to spectator mode if they die.</td>
-            <td><code>false</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SNOOPER_ENABLED</code></td>
-            <td>If set to false, the server will not send data to snoop.minecraft.net server.</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>MAX_BUILD_HEIGHT</code></td>
-            <td>The maximum height in which building is allowed. Terrain may still naturally generate above a low height limit.</td>
-            <td><code>256</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SPAWN_ANIMALS</code></td>
-            <td>Determines if animals will be able to spawn.</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SPAWN_MONSTERS</code></td>
-            <td>Determines if monsters will be spawned.</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SPAWN_NPCS</code></td>
-            <td>Determines if villagers will be spawned.</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SPAWN_PROTECTION</code></td>
-            <td>Sets the area that non-ops can not edit (0 to disable)</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>VIEW_DISTANCE</code></td>
-            <td>Sets the amount of world data the server sends the client, measured in chunks in each direction of the player (radius, not diameter). It determines the server-side viewing distance.</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SEED</code></td>
-            <td>Sets the seed to create the Minecraft world. If you use a negative number, make sure that it is in quotes.</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
        <tr>
            <td><code>MODE</code></td>
            <td>Minecraft servers are configured to run in Survival mode by default. You can change the mode using MODE where you can either provide the <a href="http://minecraft.wiki/Game_mode#Game_modes">standard numerical values</a> or the shortcut values:<br />
@@ -324,118 +228,15 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
            <td><code></code></td>
            <td>⬜️</td>
        </tr>
-        <tr>
-            <td><code>PVP</code></td>
-            <td>By default, servers are created with player-vs-player (PVP) mode enabled.</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>LEVEL_TYPE</code></td>
-            <td>By default, a standard world is generated with hills, valleys, water, etc. A different level type can be configured by setting LEVEL_TYPE to <a href="https://minecraft.wiki/w/Server.properties#level-type">an expected type listed here</a>.
-            </td>
-            <td><code>minecraft:default</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>GENERATOR_SETTINGS</code></td>
-            <td>For some of the level types, <code>GENERATOR_SETTINGS</code> can be used to further customize the world generation <a href="https://minecraft.wiki/w/Server.properties#generator-settings">as described here</a>.</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
        <tr>
            <td><code>LEVEL</code></td>
-            <td>You can either switch between world saves or run multiple containers with different saves by using the LEVEL option</td>
+            <td>Maps to <a href="https://minecraft.wiki/w/Server.properties#level-name">the <code>level-name</code> server property</a>. You can either switch between world saves or run multiple containers with different saves by using the LEVEL option</td>
            <td><code>world</code></td>
            <td>⬜️</td>
        </tr>
-        <tr>
-            <td><code>ONLINE_MODE</code></td>
-            <td>By default, server checks connecting players against Minecraft's account database. If you want to create an offline server or your server is not connected to the internet, you can disable the server to try connecting to minecraft.net to authenticate players</td>
-            <td><code>true</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>ALLOW_FLIGHT</code></td>
-            <td>Allows users to use flight on your server while in Survival mode, if they have a mod that provides flight installed.</td>
-            <td><code>FALSE</code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SERVER_NAME</code></td>
-            <td>The server name</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
        <tr>
            <td><code>SERVER_PORT</code></td>
-            <td>Only change this value if you know what you're doing. It is only needed when using host networking and it is rare that host networking should be used.</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>PLAYER_IDLE_TIMEOUT</code></td>
-            <td>player-idle-timeout</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>ENABLE_JMX</code></td>
-            <td>enable-jmx-monitoring</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SYNC_CHUNK_WRITES</code></td>
-            <td>sync-chunk-writes</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>ENABLE_STATUS</code></td>
-            <td>enable-status</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>ENTITY_BROADCAST_RANGE_PERCENTAGE</code></td>
-            <td>entity-broadcast-range-percentage</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>FUNCTION_PERMISSION_LEVEL</code></td>
-            <td>function-permission-level</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>NETWORK_COMPRESSION_THRESHOLD</code></td>
-            <td>network-compression-threshold</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>OP_PERMISSION_LEVEL</code></td>
-            <td>op-permission-level</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>PREVENT_PROXY_CONNECTIONS</code></td>
-            <td>prevent-proxy-connections</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>USE_NATIVE_TRANSPORT</code></td>
-            <td>use-native-transport</td>
-            <td><code></code></td>
-            <td>⬜️</td>
-        </tr>
-        <tr>
-            <td><code>SIMULATION_DISTANCE</code></td>
-            <td>simulation-distance</td>
+            <td>Maps to <a href="https://minecraft.wiki/w/Server.properties#server-port">the <code>server-port</code> server property</a>. Only change this value if you know what you're doing. It is only needed when using host networking and it is rare that host networking should be used.</td>
            <td><code></code></td>
            <td>⬜️</td>
        </tr>
@@ -496,6 +297,10 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
    </tbody>
 </table>

+### Server properties
+
+This image maps known server properties as described in [this section](configuration/server-properties.md).
+
 ### Custom resource pack

 <table>
--- a/docs/versions/java.md
+++ b/docs/versions/java.md
@@ -12,8 +12,8 @@ where `<tag>` refers to the first column of this table:

 | Tag            | Java version | Linux  | JVM Type           | Architecture        | Note |
 |----------------|--------------|--------|--------------------|---------------------|------|
-| latest         | 21           | Ubuntu | Hotspot            | amd64, arm64        |      |
-| stable         | 21           | Ubuntu | Hotspot            | amd64, arm64        |      |
+| latest         | 25           | Ubuntu | Hotspot            | amd64, arm64        |      |
+| stable         | 25           | Ubuntu | Hotspot            | amd64, arm64        |      |
 | java25         | 25           | Ubuntu | Hotspot            | amd64, arm64        |      |
 | java25-jdk     | 25           | Ubuntu | Hotspot+JDK        | amd64, arm64        |      |
 | java25-graalvm | 25           | Oracle | Oracle GraalVM (3) | amd64, arm64        | (5)  |   
--- a/examples/ftba/stoneblock4/compose.yml
+++ b/examples/ftba/stoneblock4/compose.yml
@@ -0,0 +1,17 @@
+services:
+  mc:
+    image: itzg/minecraft-server:java25
+    tty: true
+    stdin_open: true
+    environment:
+      EULA: "TRUE"
+      TYPE: FTBA
+      FTB_MODPACK_ID: "130"
+      FTB_MODPACK_VERSION_ID: "100171"
+      MEMORY: "4G"
+    ports:
+      - "25565:25565"
+    volumes:
+      - data:/data
+volumes:
+  data:
--- a/examples/mc-router-autoscale/compose-minimal.yml
+++ b/examples/mc-router-autoscale/compose-minimal.yml
@@ -0,0 +1,27 @@
+# Source: https://github.com/itzg/mc-router/blob/main/examples/docker-autoscale/compose-minimal.yml
+services:
+  router:
+    image: itzg/mc-router
+    environment:
+      IN_DOCKER: true
+      AUTO_SCALE_DOWN: true
+      AUTO_SCALE_UP: true
+      AUTO_SCALE_DOWN_AFTER: 2h
+      AUTO_SCALE_ASLEEP_MOTD: "Server is asleep. Join again to wake it up!"
+    ports:
+      - "25565:25565"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+  vanilla:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "TRUE"
+    labels:
+      mc-router.host: "vanilla.example.com"
+  paper:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "TRUE"
+      TYPE: PAPER
+    labels:
+      mc-router.host: "paper.example.com"
--- a/examples/mc-router-autoscale/compose.yml
+++ b/examples/mc-router-autoscale/compose.yml
@@ -0,0 +1,50 @@
+# Source: https://github.com/itzg/mc-router/blob/main/examples/docker-autoscale/compose.yml
+# This is a verbose example with comments and explanations for configuring auto-scaling behavior
+# for Docker backend servers. See compose-minimal.yml for a simple minimal example.
+services:
+  router:
+    image: itzg/mc-router
+    environment:
+      IN_DOCKER: true
+      # Global auto-scaling settings for all docker-backend servers
+      # Settings can be overridden per-backend using labels
+      # as shown in the backend services below (except for AUTO_SCALE_DOWN_AFTER which is global only)
+      # Enable auto-scaling down after inactivity for all backends by default
+      AUTO_SCALE_DOWN: true
+      # Enable auto-scaling up after player join for all backends by default
+      AUTO_SCALE_UP: true
+      # Time of inactivity after which to scale down (default: 10m) - Global only setting
+      AUTO_SCALE_DOWN_AFTER: 2h
+      # MOTD to show when server is asleep (default: empty string - don't show MOTD, show server offline instead)
+      AUTO_SCALE_ASLEEP_MOTD: "Server is asleep. Join again to wake it up!"
+    ports:
+      - "25565:25565"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+  vanilla:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "TRUE"
+    labels:
+      # If global auto scaling settings are enabled, this backend will
+      # auto-scale without any additional auto-scale related configuration
+      mc-router.host: "vanilla.example.com"
+  fabric:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "TRUE"
+      TYPE: FABRIC
+    labels:
+      mc-router.host: "fabric.example.com"
+      # Disable auto-scaling for this backend specifically
+      mc-router.auto-scale-up: false
+      mc-router.auto-scale-down: false
+  paper:
+    image: itzg/minecraft-server
+    environment:
+      EULA: "TRUE"
+      TYPE: PAPER
+    labels:
+      mc-router.host: "paper.example.com"
+      # Override asleep MOTD for this backend
+      mc-router.auto-scale-asleep-motd: "Paper is folded. Join to unfold!"
--- a/files/cf-exclude-include.json
+++ b/files/cf-exclude-include.json
@@ -35,6 +35,7 @@
    "controllable",
    "controlling",
    "craftpresence",
+    "crash-assistant",
    "cull-less-leaves",
    "ctm",
    "custom-main-menu",
@@ -100,6 +101,7 @@
    "lootbeams",
    "magnesium-extras",
    "make-bubbles-pop",
+    "mekalus-oculus-fork-with-fixed-mekanism-mekasuit",
    "menumobs",
    "minecraft-rich-presence",
    "mining-speed-tooltips",
@@ -183,7 +185,10 @@
      "forceIncludes": ["just-enough-resources-jer"]
    },
    "ftb-stoneblock-4": {
-      "forceIncludes": ["particular-reforged"]
+      "forceIncludes": [
+        "particular-reforged",
+        "ctm"
+      ]
    },
    "mc-eternal-2": {
      "forceIncludes": [
--- a/files/modrinth-exclude-include.json
+++ b/files/modrinth-exclude-include.json
@@ -32,6 +32,7 @@
    "continuity",
    "controlling",
    "craftpresence",
+    "CrashAssistant",
    "Cull Less Leaves",
    "cwb",
    "DisableCustomWorldsAdvice",
--- a/images.json
+++ b/images.json
@@ -11,7 +11,7 @@
  {
    "tag": "stable",
    "notes": "Always tracks the most recent release",
-    "java": "21",
+    "java": "25",
    "distribution": "ubuntu",
    "jvm": "hotspot",
    "architectures": ["amd64", "arm64"],
@@ -77,13 +77,6 @@
    "architectures": ["amd64", "arm64"],
    "jdk": true
  },
-  {
-    "tag": "java21-graalvm",
-    "java": "21",
-    "distribution": "oracle",
-    "jvm": "graalvm",
-    "architectures": ["amd64", "arm64"]
-  },
  {
    "tag": "java17",
    "java": "17",
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,95 +0,0 @@
---
-site_name: Minecraft Server on Docker (Java Edition)
-site_url: https://docker-minecraft-server.readthedocs.io/en/latest/
-site_description: Documentation for Minecraft Server on Docker
-repo_url: https://github.com/itzg/docker-minecraft-server
-edit_uri: blob/master/docs/
-theme:
-  name: material
-  features:
-    - navigation.tracking
-    - navigation.tabs
-    - navigation.tabs.sticky
-    - navigation.sections
-    - navigation.expand
-    - navigation.top
-    - navigation.indexes
-  locale: en
-  palette:
-    # Palette toggle for automatic mode
-    - media: "(prefers-color-scheme)"
-      toggle:
-        icon: material/brightness-auto
-        name: Switch to light mode
-
-    # Palette toggle for light mode
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-
-    # Palette toggle for dark mode
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      toggle:
-        icon: material/brightness-4
-        name: Switch to system preference
-
-  highlightjs: true
-  hljs_languages:
-    - yaml
-    - bash
-    - java
-    - docker
-    - shell
-    - json
-
-extra_css:
-  - css/extra.css
-markdown_extensions:
-  - admonition
-  - toc:
-      permalink: true
-  - attr_list
-  - def_list
-  - footnotes
-  - tables
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
-  - pymdownx.highlight:
-      anchor_linenums: true
-      line_spans: __span
-      pygments_lang_class: true
-  - pymdownx.inlinehilite
-  - pymdownx.details
-  - pymdownx.snippets
-  - pymdownx.superfences
-  - mdx_gh_links:
-      user: camalot
-      repo: mkdocs-test
-  - mkdocs-click
-copyright: Copyright &copy; itzg 2025.
-plugins:
-  - search
-  - autorefs
-  - mkdocstrings:
-      handlers:
-        python:
-          options:
-            docstring_section_style: list
-            members_order: source
-            show_root_heading: true
-            show_source: false
-            show_signature_annotations: true
-  # https://github.com/ultrabug/mkdocs-static-i18n
-  - i18n:
-      languages:
-        - locale: en
-          name: English
-          build: true
-          default: true
-  - literate-nav:
-      nav_file: README.md
-      implicit_index: true
--- a/scripts/start-configuration
+++ b/scripts/start-configuration
@@ -321,7 +321,7 @@ case "${TYPE^^}" in
      logError "Invalid TYPE: '$TYPE'"
      logError "Must be: VANILLA, FORGE, BUKKIT, SPIGOT, PAPER, FOLIA, PURPUR, FABRIC, QUILT,"
      logError "         SPONGEVANILLA, CUSTOM, MAGMA, MOHIST, GTNH, AIRPLANE, PUFFERFISH,"
-      logError "         CANYON, LIMBO, NANOLIMBO, CRUCIBLE, LEAF, YOUER, BANNER"
+      logError "         CANYON, LIMBO, NANOLIMBO, CRUCIBLE, LEAF, YOUER, BANNER, NEOFORGE"
      exit 1
  ;;

--- a/scripts/start-deployFTBA
+++ b/scripts/start-deployFTBA
@@ -93,7 +93,7 @@ if isTrue "$FTB_FORCE_REINSTALL" ||

  log "Installing modpack ID ${FTB_MODPACK_ID}, version ID ${FTB_MODPACK_VERSION_ID}"
  log "This could take a while..."
-  ${ftbInstaller} -pack "${FTB_MODPACK_ID}" -version "${FTB_MODPACK_VERSION_ID}" -auto -force | tee ftb-installer.log
+  ${ftbInstaller} -pack "${FTB_MODPACK_ID}" -version "${FTB_MODPACK_VERSION_ID}" -auto -force -no-java | tee ftb-installer.log
  rm -f forge*installer.jar

  echo "${FTB_MODPACK_ID}=${FTB_MODPACK_VERSION_ID}" > ${ftbInstallMarker}
--- a/scripts/start-deployFolia
+++ b/scripts/start-deployFolia
@@ -1,6 +1,6 @@
 #!/bin/bash

-: "${FOLIA_CHANNEL:=experimental}"
+: "${FOLIA_CHANNEL:=default}"

 # shellcheck source=start-utils
 . "$(dirname "$0")/start-utils"
--- a/scripts/start-deployGTNH
+++ b/scripts/start-deployGTNH
@@ -253,7 +253,7 @@ export ALLOW_FLIGHT="${ALLOW_FLIGHT:=true}"
 export LEVEL_TYPE="${LEVEL_TYPE:=rwg}"
 export DIFFICULTY="${DIFFICULTY:=3}"
 export ENABLE_COMMAND_BLOCK="${ENABLE_COMMAND_BLOCK:=true}"
-export MOTD="${MOTD:="Greg Tech New Horizon $GTNH_PACK_VERSION"}"
+export MOTD="${MOTD:="Greg Tech New Horizons $GTNH_PACK_VERSION"}"
 debug "Set MOTD=$MOTD, ENABLE_COMMAND_BLOCK=$ENABLE_COMMAND_BLOCK, DIFFICULTY=$DIFFICULTY, LEVEL_TYPE=$LEVEL_TYPE, ALLOW_FLIGHT=$ALLOW_FLIGHT"

 isDebugging && set -x
@@ -278,4 +278,4 @@ handleGTNH

 export USES_MODS=true

-exec "$(dirname "$0")/start-setupWorld" "$@"
+exec "$(dirname "$0")/start-setupWorld" "$@"
--- a/scripts/start-finalExec
+++ b/scripts/start-finalExec
@@ -47,7 +47,7 @@ if [ -n "$ICON" ]; then
    fi
 fi

-canUseRollingLogs=true
+useGeneratedLogs=${GENERATE_LOG4J2_CONFIG:-${ENABLE_ROLLING_LOGS:-false}}
 useFallbackJvmFlag=false

 SERVER_DIR="$baseDataDir"
@@ -65,7 +65,7 @@ patchLog4jConfig() {
    return 1
  fi
  JVM_OPTS="-Dlog4j.configurationFile=${file} ${JVM_OPTS}"
-  canUseRollingLogs=false
+  useGeneratedLogs=false
 }

 # Temporarily disable debugging output
@@ -104,7 +104,8 @@ elif versionLessThan 1.18.1; then
 fi

 # Set up log4j2 configuration with templating support
-if ${canUseRollingLogs}; then
+LOGFILE="${SERVER_DIR}/log4j2.xml"
+if ${useGeneratedLogs}; then
  # Set up log configuration defaults
  : "${LOG_LEVEL:=info}"
  : "${ROLLING_LOG_MAX_FILES:=1000}"
@@ -128,10 +129,9 @@ if ${canUseRollingLogs}; then
  export LOG_LEVEL ROLLING_LOG_FILE_PATTERN ROLLING_LOG_MAX_FILES
  export LOG_CONSOLE_FORMAT LOG_TERMINAL_FORMAT LOG_FILE_FORMAT

-  LOGFILE="${SERVER_DIR}/log4j2.xml"

-  # Always regenerate if file doesn't exist or REGENERATE_LOG4J2 is set
-  if [ ! -e "$LOGFILE" ] || isTrue "${REGENERATE_LOG4J2:-false}"; then
+  # Always regenerate if file doesn't exist
+  if [ ! -e "$LOGFILE" ] || isTrue "${REGENERATE_LOG4J2:-true}"; then
    log "Generating log4j2.xml from template in ${LOGFILE}"

    # Generate log4j2.xml using heredoc for reliable variable substitution
@@ -142,6 +142,9 @@ if ${canUseRollingLogs}; then
        <Console name="SysOut" target="SYSTEM_OUT">
            <PatternLayout pattern="${LOG_CONSOLE_FORMAT}" />
        </Console>
+        <Queue name="TerminalConsole">
+            <PatternLayout pattern="${LOG_TERMINAL_FORMAT}" />
+        </Queue>
        <RollingRandomAccessFile name="File" fileName="logs/latest.log" filePattern="${ROLLING_LOG_FILE_PATTERN}">
            <PatternLayout pattern="${LOG_FILE_FORMAT}" />
            <Policies>
@@ -169,10 +172,8 @@ EOF

  # Apply the log4j2 configuration
  JVM_OPTS="-Dlog4j.configurationFile=log4j2.xml ${JVM_OPTS}"
-elif isTrue "${ENABLE_ROLLING_LOGS:-false}"; then
-  # Legacy behavior: error if rolling logs explicitly requested but not possible
-  logError "Using rolling logs is currently not possible in the selected version due to CVE-2021-44228"
-  exit 1
+else
+  rm -f "${LOGFILE}"
 fi

 # Optional disable console
--- a/scripts/start-setupModpack
+++ b/scripts/start-setupModpack
@@ -11,7 +11,10 @@ set -e -o pipefail
 : "${REMOVE_OLD_MODS_INCLUDE:=*.jar,*-version.json}"
 : "${CF_API_KEY_FILE:=}" # Path to file containing CurseForge API key
 : "${MODRINTH_LOADER:=}"
-sum_file=/data/.generic_pack.sum
+
+# shellcheck source=start-utils
+. "$(dirname "$0")/start-utils"
+isDebugging && set -x

 if [[ -n ${CF_API_KEY_FILE} ]]; then
  if [[ -r "${CF_API_KEY_FILE}" ]]; then
@@ -23,13 +26,7 @@ if [[ -n ${CF_API_KEY_FILE} ]]; then
  fi
 fi

-# shellcheck source=start-utils
-. "$(dirname "$0")/start-utils"
-isDebugging && set -x
-
-#  CURSE_URL_BASE used in manifest downloads below
-CURSE_URL_BASE=${CURSE_URL_BASE:-https://minecraft.curseforge.com/projects}
-
+sum_file=/data/.generic_pack.sum
 # Remove old mods/plugins
 if isTrue "${REMOVE_OLD_MODS}" && [ -z "${MODS_FILE}" ]; then
  removeOldMods "$MODS_OUT_DIR"
--- a/zensical.toml
+++ b/zensical.toml
@@ -0,0 +1,41 @@
+[project]
+site_name = "Minecraft Server on Docker (Java Edition)"
+site_url = "https://docker-minecraft-server.readthedocs.io/en/latest/"
+site_description = "Documentation for Minecraft Server on Docker"
+repo_name = "itzg/docker-minecraft-server"
+repo_url = "https://github.com/itzg/docker-minecraft-server"
+site_author = "itzg"
+copyright = "Copyright &copy; itzg 2026."
+docs_dir = "docs"
+site_dir = "site"
+
+[project.theme]
+features = [
+    "navigation.tracking",
+    "navigation.tabs",
+    "navigation.tabs.sticky",
+    "navigation.sections",
+    "navigation.top",
+    "navigation.indexes"
+]
+language = "en"
+
+[project.theme.icon]
+repo = "fontawesome/brands/github"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme)"
+toggle.icon = "lucide/sun-moon"
+toggle.name = "Switch to light mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
Author	SHA1	Message	Date
Geoff Bourne	6bb401f9ff	cf: resolve remaining exclude/include slugs after first unknown mod (#3909 )	2026-02-04 06:57:22 -06:00
Geoff Bourne	82266fff97	Put back particle-effects-reforged and flerovium in global excludes (#3906 )	2026-02-03 19:02:36 -06:00
Geoff Bourne	92b4babc86	autocf: log warning and proceed if an excluded mod cannot be resolved (#3904 )	2026-02-03 10:13:25 -06:00
Geoff Bourne	83435738f4	Temporarily remove flerovium from global excludes (#3903 )	2026-02-03 08:51:04 -06:00
Geoff Bourne	a9dd219f78	Temporarily remove particle-effects-reforged from global excludes (#3902 )	2026-02-03 07:33:06 -06:00
dependabot[bot]	90ac9589e3	build(deps): bump docker/login-action from 3.6.0 to 3.7.0 in the updates group (#3900 )	2026-02-02 07:11:03 -06:00
dependabot[bot]	9520b06095	build(deps): bump pathspec from 1.0.3 to 1.0.4 in /docs in the patches group (#3901 )	2026-02-02 07:08:18 -06:00
Geoff Bourne	1ae5e4d748	Temporarily remove GraalVM variants from build (#3899 )	2026-02-01 15:38:30 -06:00
Geoff Bourne	d43802ebd4	Removed duplicate in images.json (#3891 )	2026-02-01 15:36:19 -06:00
Geoff Bourne	4677d9065d	Update build badge in README.md (#3898 )	2026-02-01 15:30:55 -06:00
Sagittarius-a	4f6de31e38	docs: fix link formatting in environment variables documentation page (#3895 )	2026-01-31 17:46:55 -06:00
Geoff Bourne	941e25c4b9	Temporarily disable auto-pause with graalvm images (#3893 )	2026-01-29 18:43:23 -06:00
Geoff Bourne	621c673acd	Leave docs sidebar nav collapsed by default (#3892 )	2026-01-28 19:32:47 -06:00
Thomas Nicollet	fb1614b149	Fixing typo in GTNH MOTD (#3889 )	2026-01-27 07:12:53 -06:00
dependabot[bot]	feec7fb6bd	build(deps): bump the patches group in /docs with 3 updates (#3886 )	2026-01-26 09:04:56 -06:00
dependabot[bot]	f27eb08440	build(deps): bump packaging from 25.0 to 26.0 in /docs (#3887 )	2026-01-26 07:40:20 -06:00
dependabot[bot]	183e0cd18f	build(deps): bump actions/checkout from 6.0.1 to 6.0.2 in the updates group (#3885 )	2026-01-26 07:00:52 -06:00
Geoff Bourne	4b24251d70	Clarify scope of LOG_LEVEL (#3878 )	2026-01-22 07:26:35 -06:00
Geoff Bourne	7678f52939	Fix logError call when using CF_API_KEY_FILE (#3818 )	2026-01-22 07:25:55 -06:00
Lenart Kos	c1d5241fb2	Add autoscaling documentation and examples for mc-router integration (#3826 )	2026-01-20 12:59:04 -06:00
Geoff Bourne	1565d08949	Avoid confusion about server properties supportability (#3875 )	2026-01-20 07:47:47 -06:00
Tanner Snow	816ab736d9	Fix minor typos in GTNH docs (#3872 )	2026-01-17 08:59:46 -06:00
dependabot[bot]	32b343840f	build(deps): bump pymdown-extensions from 10.19.1 to 10.20 in /docs in the patches group (#3864 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-01-13 07:16:32 -06:00
Geoff Bourne	0a98bee40e	Ensure FTBA uses image's java (#3867 )	2026-01-12 20:56:50 -06:00
dependabot[bot]	93d94f5ba8	build(deps): bump pathspec from 0.12.1 to 1.0.3 in /docs (#3865 )	2026-01-12 13:07:02 -06:00
Damián	f3ed09882b	Add mekalus to cf-exclude-include.json (#3862 )	2026-01-11 07:58:10 -06:00
Geoff Bourne	7325baf750	Default Folia channel to stable rather than experimental (#3861 )	2026-01-08 18:28:04 -06:00
Geoff Bourne	c23654008b	Leverage ENABLE_ROLLING_LOGS as default for GENERATE_LOG4J2_CONFIG (#3860 )	2026-01-08 18:16:13 -06:00
Geoff Bourne	f8ff8a7b8a	Opt into generated log4j2.xml configuration (#3856 )	2026-01-08 07:25:01 -06:00
EmilyxFox	9c01462c0c	Docs: cleanup copyright year and contributing (#3855 )	2026-01-07 07:48:14 -06:00
EmilyxFox	21c5c980d5	Move docs to zensical (#3852 )	2026-01-06 06:36:04 -06:00
dependabot[bot]	4458908a44	build(deps): bump the patches group across 1 directory with 2 updates (#3825 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-01-05 07:12:33 -06:00
Geoff Bourne	c9094063d3	Bump latest/stable image variant to java25 (#3845 )	2025-12-31 16:38:59 -06:00
Geoff Bourne	320ad0906f	Adding back TerminalConsole to generated log4j2 config (#3846 )	2025-12-31 14:46:49 -06:00
EmilyxFox	128bbff3d7	Document SSH console and RCON password secrets file (#3843 )	2025-12-30 11:53:29 -06:00
Igor Fontana	82aafd5f5e	Add NEOFORGE to invalid type message (#3842 )	2025-12-30 06:57:57 -06:00
Luke Van De Weghe	f746162360	Globally exclude crash-assistant mod (#3839 )	2025-12-28 17:44:10 -06:00
Kim	0131f66e46	Add 'ctm' to forceIncludes for ftb-stoneblock-4 (#3840 )	2025-12-28 08:49:03 -06:00