Compare commits

...

23 Commits

Author SHA1 Message Date
Geoff Bourne
ef9c4e9195 GFM doesn't render custom divs
Removed test content from the README file.
2026-04-11 18:40:46 -05:00
Geoff Bourne
d50e580d85 Add test content to sponsors entry 2026-04-11 18:39:22 -05:00
Geoff Bourne
73d5d98ab2 Add sponsors section 2026-04-11 18:37:56 -05:00
renovate[bot]
eb4fe3c7bf Update dependency itzg/mc-image-helper to v1.56.1 (#4005) 2026-04-09 21:48:28 -05:00
Geoff Bourne
8c9e2c653f Added dev docs for building image with tool version change (#4007) 2026-04-09 11:02:32 -05:00
Vianney Veremme
bd98fe57ba Add optional Modrinth projects support (? suffix) documentation (#4004) 2026-04-09 10:15:11 -05:00
dependabot[bot]
23205471db build(deps): bump the patches group in /docs with 2 updates (#4001) 2026-04-06 07:49:39 -05:00
EmilyxFox
f8618a5360 add more examples for new minecraft version schema (#3981) 2026-04-05 11:25:32 -05:00
renovate[bot]
acc90757a6 chore(deps): update dependency itzg/mc-server-runner to v1.14.5 (#3999)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-04-05 10:07:11 -05:00
Geoff Bourne
589872049f Added default exclude of smooth swapping (#3992) 2026-03-31 11:38:50 -05:00
dependabot[bot]
18403e7db8 build(deps): bump the patches group across 1 directory with 4 updates (#3996) 2026-03-30 13:37:28 -05:00
renovate[bot]
2625ca2b3c chore(deps): update dependency itzg/mc-server-runner to v1.14.4 (#3993)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-03-28 13:24:01 -05:00
Geoff Bourne
5b9c09b7b2 Pin mcVersion to 1.21.11 for Java 21 build testing (#3991) 2026-03-26 15:54:10 -05:00
Jason Walton
b37c2cc3ef Add RCON_PASSWORD_FILE to variables.md. (#3989) 2026-03-26 15:42:22 -05:00
Geoff Bourne
3cd3656868 Consider MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE as part of VERSION_FROM_MODRINTH_PROJECTS (#3985) 2026-03-22 19:52:07 -05:00
renovate[bot]
387c674849 chore(deps): update dependency itzg/mc-image-helper to v1.55.3 (#3984)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-03-22 08:45:41 -05:00
Geoff Bourne
fba656561f Add image variant java25-alpine (#3980) 2026-03-17 21:06:00 -05:00
Geoff Bourne
cf8ab31e25 Apply logging prefix on output from DEBUG_MEMORY (#3975) 2026-03-17 08:04:46 -05:00
dependabot[bot]
68bb650617 build(deps): bump the patches group in /docs with 2 updates (#3976) 2026-03-16 07:30:31 -05:00
renovate[bot]
c5a298fa05 chore(deps): update dependency itzg/rcon-cli to v1.7.4 (#3973) 2026-03-13 07:30:23 -05:00
Geoff Bourne
5dff0b8541 notes: removed start-setupForgeApiMods from start flow diagram (#3972) 2026-03-12 16:08:06 -05:00
renovate[bot]
9c9a3a8b43 chore(deps): update dependency itzg/mc-server-runner to v1.14.3 (#3971) 2026-03-10 22:23:09 -05:00
dependabot[bot]
3bbe3b7c80 build(deps): bump platformdirs from 4.9.2 to 4.9.4 in /docs in the patches group (#3970) 2026-03-09 07:31:56 -05:00
21 changed files with 162 additions and 34 deletions

View File

@@ -27,6 +27,7 @@ jobs:
# NOTE: the "latest" variant is identified in the Docker meta step's 'latest' config
variant:
- java25
- java25-alpine
- java25-jdk
- java21
- java21-alpine
@@ -42,6 +43,10 @@ jobs:
baseImage: eclipse-temurin:25-jre
platforms: linux/amd64,linux/arm64
mcVersion: latest
- variant: java25-alpine
baseImage: eclipse-temurin:25-jre-alpine
platforms: linux/amd64,linux/arm64
mcVersion: latest
- variant: java25-jdk
baseImage: eclipse-temurin:25
platforms: linux/amd64,linux/arm64
@@ -50,15 +55,15 @@ jobs:
- variant: java21
baseImage: eclipse-temurin:21-jre
platforms: linux/amd64,linux/arm64
mcVersion: latest
mcVersion: 1.21.11
- variant: java21-jdk
baseImage: eclipse-temurin:21
platforms: linux/amd64,linux/arm64
mcVersion: latest
mcVersion: 1.21.11
- variant: java21-alpine
baseImage: eclipse-temurin:21-jre-alpine
platforms: linux/amd64,linux/arm64
mcVersion: latest
mcVersion: 1.21.11
# JAVA 17:
- variant: java17
# jammy doesn't work until minecraft updates to https://github.com/netty/netty/issues/12343

View File

@@ -23,7 +23,7 @@ jobs:
matrix:
variant:
- java25
- java21-alpine
- java25-alpine
- java17
- java8
include:
@@ -32,8 +32,8 @@ jobs:
baseImage: eclipse-temurin:25-jre
platforms: linux/amd64,linux/arm64
mcVersion: latest
- variant: java21-alpine
baseImage: eclipse-temurin:21-jre-alpine
- variant: java25-alpine
baseImage: eclipse-temurin:25-jre-alpine
platforms: linux/amd64,linux/arm64
mcVersion: latest
# JAVA 17:

View File

@@ -37,7 +37,7 @@ RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
--from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
# renovate: datasource=github-releases packageName=itzg/rcon-cli
ARG RCON_CLI_VERSION=1.7.3
ARG RCON_CLI_VERSION=1.7.4
RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
--var version=${RCON_CLI_VERSION} --var app=rcon-cli --file {{.app}} \
--from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
@@ -49,13 +49,13 @@ RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
--from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
# renovate: datasource=github-releases packageName=itzg/mc-server-runner
ARG MC_SERVER_RUNNER_VERSION=1.14.2
ARG MC_SERVER_RUNNER_VERSION=1.14.5
RUN easy-add --var os=${TARGETOS} --var arch=${TARGETARCH}${TARGETVARIANT} \
--var version=${MC_SERVER_RUNNER_VERSION} --var app=mc-server-runner --file {{.app}} \
--from ${GITHUB_BASEURL}/itzg/{{.app}}/releases/download/{{.version}}/{{.app}}_{{.version}}_{{.os}}_{{.arch}}.tar.gz
# renovate: datasource=github-releases packageName=itzg/mc-image-helper versioning=loose
ARG MC_HELPER_VERSION=1.55.2
ARG MC_HELPER_VERSION=1.56.1
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

View File

@@ -6,7 +6,7 @@
[![](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)
[![Read the docs](docs/img/docs-banner.png)](https://docker-minecraft-server.readthedocs.io/)
[![Read the docs](docs/img/banner-docs.png)](https://docker-minecraft-server.readthedocs.io/)
There you will find things like
- [Quick start with Docker Compose](https://docker-minecraft-server.readthedocs.io/en/latest/#using-docker-compose)
@@ -19,3 +19,6 @@ There you will find things like
There are also many examples located in [the examples directory](examples) of this repo.
This image only supports Java edition natively; however, if looking for a server that is compatible with Bedrock edition, then use [itzg/minecraft-bedrock-server](https://github.com/itzg/docker-minecraft-bedrock-server) or [refer to this section](https://docker-minecraft-server.readthedocs.io/en/latest/misc/examples/#bedrock-compatible-server) to add Bedrock compatibility to a Java edition server.
## ![Sponsors](docs/img/banner-sponsors.png)

View File

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 29 KiB

View File

@@ -6,7 +6,7 @@ Small, none, Minecraftia
Line 2:
"Documentation"
Large, non, Minecrafter
Large, none, Minecrafter
Overall settings:
- drop shadow

Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

View File

@@ -0,0 +1,9 @@
Generated at https://textcraft.net/
Line 1:
"Sponsors"
Mid
None
Minecrafter
Drop shadow
3d-style view

View File

@@ -21,6 +21,30 @@ docker compose -f compose-dev.yml run --rm -it [-e key=value] mc-dev
To speed up the development cycle, it is recommended to set `SETUP_ONLY` to `true` as part of the run command above.
## Building the image with a new release of a tool
In this exapmle, let's say that [mc-image-helper](https://github.com/itzg/mc-image-helper) has been [released](https://github.com/itzg/mc-image-helper/releases) at 1.56.0, but the corresponding changes in the image [scripts](https://github.com/itzg/docker-minecraft-server/tree/23205471db9814cff9c6602361dbc6cdd6c4230a/scripts) need to be tested against that version while updating [the Dockerfile](https://github.com/itzg/docker-minecraft-server/blob/23205471db9814cff9c6602361dbc6cdd6c4230a/Dockerfile#L58).
```yaml title="tests/manual/optional-projects/compose.yml" hl_lines="7"
services:
mc:
build:
# ...or wherever you cloned the docker-minecraft-server repo
context: ../../..
args:
MC_HELPER_VERSION: 1.56.0
environment:
EULA: true
TYPE: "FABRIC"
MODRINTH_PROJECTS: |
fabric-api
pl3xmap?:beta
ports:
- "25565:25565/tcp"
volumes:
- ./data:/data
```
## Using development copy of tools
In the cloned repo, such as [`mc-image-helper`](https://github.com/itzg/mc-image-helper), install the distribution locally by running:

View File

@@ -86,6 +86,54 @@ Where:
To temporarily disable processing of the `MODRINTH_PROJECTS` list, then comment out the `MODRINTH_PROJECTS` environment variable.
## Optional projects
Projects that are not critical for the server to function can be marked as **optional** by appending a `?` to the project slug or ID. When a compatible version cannot be found for an optional project, the server logs a warning and continues startup instead of failing.
This is particularly useful for server-side mods that tend to lag behind on Minecraft updates, such as map renderers (Pl3xmap, BlueMap), performance mods (Lithium, C2ME), or admin tools (Spark, LuckPerms).
```yaml
MODRINTH_PROJECTS: |
fabric-api
lithium
pl3xmap?
bluemap?:beta
```
The `?` marker can be combined with all existing format options:
| Format | Example |
|----------------------------|---------------------------|
| Slug only | `pl3xmap?` |
| With version | `pl3xmap?:Oa9ZDzZq` |
| With release type | `pl3xmap?:beta` |
| With loader prefix | `fabric:pl3xmap?` |
| Full combination | `fabric:pl3xmap?:beta` |
| In listing files | `pl3xmap?` *(one per line)* |
When combined with [`VERSION_FROM_MODRINTH_PROJECTS`](#version-from-projects), optional projects are **excluded** from the version calculation. This means an optional mod that hasn't been updated yet will never block a Minecraft version upgrade.
!!! example "Automatic upgrades without optional-mod breakage"
```yaml
MODRINTH_PROJECTS: |
fabric-api
lithium
pl3xmap?
VERSION_FROM_MODRINTH_PROJECTS: true
```
If a new Minecraft version is released and `fabric-api` + `lithium` support it but `pl3xmap` does not:
1. The resolved `VERSION` is set to the new version (pl3xmap is not considered)
2. `fabric-api` and `lithium` are installed normally
3. `pl3xmap` is skipped with a warning in the logs
4. On a future restart, once pl3xmap publishes a compatible build, it is picked up automatically
!!! note
Optional projects marked with `?` in listing files (`@/path/to/file.txt`) are supported ; the `?` is parsed from each line the same way as inline entries.
## Version from Projects
When the environment variable `VERSION_FROM_MODRINTH_PROJECTS` is set to "true" the Minecraft [`VERSION`](../versions/minecraft.md) will be automatically determined by looking at the most recent version of Minecraft that is supported by all the projects provided in `MODRINTH_PROJECTS`.
@@ -115,4 +163,3 @@ When the environment variable `VERSION_FROM_MODRINTH_PROJECTS` is set to "true"
`MODRINTH_LOADER`
: When using a custom server, set this to specify which loader type will be requested during lookups

View File

@@ -1,25 +1,25 @@
click==8.3.1
click==8.3.2
colorama==0.4.6
deepmerge==2.0
ghp-import==2.1.0
griffe==2.0.0
griffe==2.0.2
Jinja2==3.1.6
Markdown==3.10.2
MarkupSafe==3.0.3
mergedeep==1.3.4
mkdocs==1.6.1
mkdocs-autorefs==1.4.4
mkdocs-get-deps==0.2.0
mkdocs-get-deps==0.2.2
mkdocstrings==1.0.3
mkdocstrings-python==2.0.3
packaging==26.0
pathspec==1.0.4
platformdirs==4.9.2
Pygments==2.19.2
pymdown-extensions==10.21
platformdirs==4.9.4
Pygments==2.20.0
pymdown-extensions==10.21.2
python-dateutil==2.9.0.post0
PyYAML==6.0.3
pyyaml_env_tag==1.1
six==1.17.0
watchdog==6.0.0
zensical==0.0.24
zensical==0.0.31

View File

@@ -397,6 +397,12 @@ This image maps known server properties as described in [this section](configura
<td><code>Randomly generated</code></td>
<td>✅</td>
</tr>
<tr>
<td><code>RCON_PASSWORD_FILE</code></td>
<td>Can be set to read the RCON password from a file. Overrides <code>RCON_PASSWORD</code> if both are set.</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>RCON_PORT</code></td>
<td>The port for RCON</td>

View File

@@ -15,25 +15,19 @@ where `<tag>` refers to the first column of this table:
| latest | 25 | Ubuntu | Hotspot | amd64, arm64 | |
| stable | 25 | Ubuntu | Hotspot | amd64, arm64 | |
| java25 | 25 | Ubuntu | Hotspot | amd64, arm64 | |
| java25-alpine | 25 | Alpine | Hotspot | amd64, arm64 | |
| java25-jdk | 25 | Ubuntu | Hotspot+JDK | amd64, arm64 | |
| java25-graalvm | 25 | Oracle | Oracle GraalVM (3) | amd64, arm64 | (5) |
| java21 | 21 | Ubuntu | Hotspot | amd64, arm64 | |
| java21-jdk | 21 | Ubuntu | Hotspot+JDK | amd64, arm64 | |
| java21-alpine | 21 | Alpine | Hotspot | amd64, arm64 | |
| java21-graalvm | 21 | Oracle | Oracle GraalVM (3) | amd64, arm64 | (5) |
| java17 | 17 | Ubuntu | Hotspot | amd64, arm64, armv7 | |
| java17-graalvm | 17 | Oracle | Oracle GraalVM (3) | amd64, arm64 | (5) |
| java16 | 16 | Ubuntu | Hotspot | amd64, arm64, armv7 | (4) |
| java16 | 16 | Ubuntu | Hotspot | amd64, arm64, armv7 | (1) |
| java11 | 11 | Ubuntu | Hotspot | amd64, arm64, armv7 | |
| java8 | 8 | Ubuntu | Hotspot | amd64, arm64, armv7 | |
Notes
1. Why no arm64 for Java 17 Alpine? That is because the base images, such as [elipse-temurin](https://hub.docker.com/_/eclipse-temurin/tags?page=&page_size=&ordering=&name=17-jre-alpine) do not provide support for that. Use the Ubuntu-based images instead.
2. Short-term variant, subject to deprecation upon next version introduction
3. Based on the [Oracle GraalVM images](https://blogs.oracle.com/java/post/new-oracle-graalvm-container-images), which as of JDK 17, are now under the [GraalVM Free License](https://blogs.oracle.com/java/post/graalvm-free-license) incorporating what used to be known as the GraalVM Enterprise.
4. This version of Java is [recommended for PaperMC 1.16.5](https://docs.papermc.io/paper/getting-started/#requirements)
5. Due to these images using Oracle Linux, (which is based on Red Hat Enterprise Linux) Forge Installer will not work due to its use of zlib-ng. Use other images for initial installation and Forge version upgrade.
1. This version of Java is [recommended for PaperMC 1.16.5](https://docs.papermc.io/paper/getting-started/#requirements)
!!! example "Example using java8"
@@ -127,6 +121,7 @@ Forge also doesn't support openj9 JVM implementation.
The following image tags have been deprecated and are no longer receiving updates:
- java25-graalvm, java21-graalvm, java17-graalvm
- adopt13
- adopt14
- adopt15

View File

@@ -2,7 +2,8 @@ To use a different Minecraft version, pass the `VERSION` environment variable (c
- `LATEST` for latest release (the default)
- `SNAPSHOT` for latest snapshot
- a specific version, such as `1.7.9`, `25w35a`, `26.1`, or `26.1-snapshot-1`
- a specific legacy version, such as `1.7.9`, `25w35a`, `1.15.2-pre2` or `1.21.11-rc1`
- a specific [new version numbering system](https://www.minecraft.net/en-us/article/minecraft-new-version-numbering-system) version like `26.1`, `26.1-snapshot-1`, `26.1-pre-1`, or `26.1-rc-1`
- or an alpha and beta version, such as "b1.7.3" (server download might not exist)
For example, to use the latest snapshot:

View File

@@ -144,6 +144,7 @@
"smart-hud",
"smithing-template-viewer",
"smooth-font",
"smooth-swapping",
"smoothwater",
"sodium",
"sodium-extra",

View File

@@ -94,6 +94,7 @@
"seasonhud",
"ShoulderSurfing",
"skinlayers3d",
"smoothswapping",
"sodium",
"sorted_enchantments",
"tooltipfix",

View File

@@ -24,12 +24,20 @@
"jvm": "hotspot",
"architectures": ["amd64", "arm64"]
},
{
"tag": "java25-alpine",
"java": "25",
"distribution": "alpine",
"jvm": "hotspot",
"architectures": ["amd64", "arm64"]
},
{
"tag": "java25-graalvm",
"java": "25",
"distribution": "oracle",
"jvm": "graalvm",
"architectures": ["amd64", "arm64"]
"architectures": ["amd64", "arm64"],
"deprecated": true
},
{
"tag": "java24",
@@ -67,7 +75,8 @@
"java": "21",
"distribution": "oracle",
"jvm": "graalvm",
"architectures": ["amd64", "arm64"]
"architectures": ["amd64", "arm64"],
"deprecated": true
},
{
"tag": "java21-jdk",

Binary file not shown.

Before

Width:  |  Height:  |  Size: 83 KiB

After

Width:  |  Height:  |  Size: 75 KiB

View File

@@ -54,8 +54,8 @@ fi
if isTrue "${DEBUG_MEMORY:-false}"; then
log "Memory usage and availability (in MB)"
uname -pars
free -m
uname -pars | applyLogPrefix
free -m | applyLogPrefix
fi
##########################################
@@ -156,7 +156,11 @@ export DECLARED_TYPE=${TYPE^^}
export DECLARED_VERSION="$VERSION"
if isTrue "${VERSION_FROM_MODRINTH_PROJECTS:-}" && [[ ${MODRINTH_PROJECTS:-} ]]; then
if ! VERSION=$(mc-image-helper version-from-modrinth-projects --projects "${MODRINTH_PROJECTS}"); then
args=()
if [[ ${MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE:-} ]]; then
args+=(--allowed-version-type "${MODRINTH_PROJECTS_DEFAULT_VERSION_TYPE:-}")
fi
if ! VERSION=$(mc-image-helper version-from-modrinth-projects "${args[@]}" --projects "${MODRINTH_PROJECTS}"); then
logError "failed to resolve version from MODRINTH_PROJECTS: ${MODRINTH_PROJECTS}"
exit 1
fi

View File

@@ -125,6 +125,12 @@ function logn() {
echo -n "[init] $*"
}
# Use as
# cmd | applyLogPrefix
function applyLogPrefix() {
sed 's/^/[init] /'
}
function log() {
local oldState
# The return status when listing options is zero if all optnames are enabled, non- zero otherwise.

View File

@@ -0,0 +1,17 @@
services:
mc:
build:
# ...or wherever you cloned the docker-minecraft-server repo
context: ../../..
args:
MC_HELPER_VERSION: 1.56.0
environment:
EULA: true
TYPE: "FABRIC"
MODRINTH_PROJECTS: |
fabric-api
pl3xmap?:beta
ports:
- "25565:25565/tcp"
volumes:
- ./data:/data