### Docker Commands for Server Setup

Source: https://github.com/itzg/docker-minecraft-server/wiki/Minecraft-Pi

Pull the latest Minecraft server Docker image and then start the server using docker-compose up. Ensure docker-compose is installed and the docker-compose.yml file is in the current directory.

```bash
$ docker pull itzg/minecraft-server  # Get the latest image
$ docker-compose up
```

--------------------------------

### Example Listing File for CURSEFORGE_FILES

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/curseforge-files.md

This example shows the format of a listing file used with CURSEFORGE_FILES. Blank lines and lines starting with '#' are ignored. Each valid line is treated as a project-file reference.

```text
# This comment is ignored
jei:10.2.1.1005

# This and previous blank line are ignore
geckolib
aquaculture
naturalist
```

--------------------------------

### Example Init Log with Timestamp

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/misc-options.md

This example shows the format of initialization logs when LOG_TIMESTAMP is enabled, including the timestamp prefix.

```text
[init] 2022-02-05 16:58:33+00:00 Starting the Minecraft server...
```

--------------------------------

### Modrinth Projects Listing File Example

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/modrinth.md

A listing file can contain a list of Modrinth projects, one per line. Blank lines and lines starting with '#' are ignored. Ensure the file is accessible via a volume mount.

```text
# This comment is ignored
fabric-api

# This and previous blank line are ignore
cloth-config
datapack:terralith
```

--------------------------------

### Start Minecraft and mc-router Services

Source: https://github.com/itzg/docker-minecraft-server/blob/master/examples/podman-quadlets/README.md

Enable and start the Podman socket, then start the Minecraft instance and mc-router services. Also, enable a specific Minecraft instance by creating a symlink.

```sh
systemctl --user enable --now podman.socket
systemctl --user start mc@example.service mc-router.service
# instances are enabled by symlinking from the template
ln -s ${XDG_CONFIG_HOME}/containers/systemd/mc@.service ${XDG_CONFIG_HOME}/containers/systemd/mc@example.service
```

--------------------------------

### Example RCON command rules for new players

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/auto-rcon-commands.md

This example demonstrates setting up RCON commands for new players, including team management and item distribution. It utilizes startup and on-connect commands to manage player teams and provide items.

```yaml
      RCON_CMDS_STARTUP:  |-
        /pregen start 200
        /gamerule doFireTick false
        /team add New
        /team add Old
```

```yaml
      RCON_CMDS_ON_CONNECT: |- 
        /team join New @a[team=]
        /give @a[team=New] birch_boat
        /team join Old @a[team=New]
```

```yaml
      RCON_CMDS_FIRST_CONNECT: |- 
        /pregen stop
```

```yaml
      RCON_CMDS_LAST_DISCONNECT: |- 
        /kill @e[type=minecraft:boat]
        /pregen start 200
```

--------------------------------

### Install py3minepi and Connect to Server

Source: https://github.com/itzg/docker-minecraft-server/wiki/Minecraft-Pi

Install the py3minepi Python library using pip. Then, use a Python one-liner to connect to the Minecraft server at 'my-docker-server.local' and post a chat message.

```bash
$ pip install py3minepi
$ python -c 'from mcpi.minecraft import Minecraft; mc = Minecraft.create("my-docker-server.local"); mc.postToChat("Hello World!")'
```

--------------------------------

### Install Local mc-image-helper Distribution

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/contributing/development.md

Install the local distribution of mc-image-helper. The output path is needed for volume mounting in Docker.

```shell
./gradlew installDist
```

--------------------------------

### Install Datapacks via URL List

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/world-data.md

Provide a comma-separated list of URLs, container paths, or directories to install datapacks. Datapacks are placed in /data/$LEVEL/datapacks.

```bash
docker run -d -e DATAPACKS=http://example.com/dp1.zip,/path/to/dp2,/path/to/dp3 ...
```

--------------------------------

### VanillaTweaks Files Example

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/world-data.md

Provide a comma-separated list of paths to JSON files containing VanillaTweaks configurations.

```yaml
VANILLATWEAKS_FILE: /config/vt-datapacks.json,/config/vt-craftingtweaks.json,/config/vt-resourcepacks.json
```

--------------------------------

### Full compose.yaml Example with SSH Enabled

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/sending-commands/ssh.md

This example demonstrates a complete compose.yaml configuration for the Minecraft server, including enabling SSH access, setting the EULA, and configuring RCON password management.

```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
```

--------------------------------

### Use a Pre-downloaded Forge Installer

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/forge.md

To use a local Forge installer, mount the installer file into the container and specify its path using the FORGE_INSTALLER environment variable. This bypasses the need for VERSION and FORGE_VERSION.

```yaml
environment:
  TYPE: FORGE
  FORGE_INSTALLER: /path/to/your/forge-installer.jar
```

--------------------------------

### Example .env file within a Generic Pack

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/index.md

An example .env file that can be included in a generic pack to set server variables. This file is sourced by bash.

```env
TYPE=FABRIC
VERSION=1.21.1
FABRIC_LOADER_VERSION=0.16.0
```

--------------------------------

### Install Datapacks via File

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/world-data.md

Specify a text file within the container where each line is a URL, container path, or directory for datapacks to be installed. Datapacks are placed in /data/$LEVEL/datapacks.

```bash
docker run -d -e DATAPACKS_FILE=/path/to/datapack_list.txt ...
```

--------------------------------

### Use Cleanroom with Forge Installer URL

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/forge.md

Utilize Cleanroom by setting TYPE to FORGE and providing the download URL for the Cleanroom installer JAR via FORGE_INSTALLER_URL.

```yaml
environment:
  TYPE: FORGE
  FORGE_INSTALLER_URL: https://github.com/CleanroomMC/Cleanroom/releases/download/0.2.4-alpha/cleanroom-0.2.4-alpha-installer.jar
```

--------------------------------

### Add Nvidia GPU Support with Dockerfile

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/building.md

This example demonstrates adding Nvidia GPU support by installing OpenCL loader and NVIDIA driver capabilities within an inline Dockerfile. It also configures environment variables for the NVIDIA container runtime.

```yaml
services:
  mc:
    build:
      context: .
      dockerfile_inline: |
        FROM itzg/minecraft-server:java25

        # Install OpenCL loader and NVIDIA driver capabilities
        RUN apt-get update && apt-get install -y \
            ocl-icd-libopencl1 \
            opencl-headers \
            clinfo \
            && rm -rf /var/lib/apt/lists/*

        # 1. Create the vendor directory
        # 2. Tell OpenCL to use the NVIDIA library
        RUN mkdir -p /etc/OpenCL/vendors && \
            echo "libnvidia-opencl.so.1" > /etc/OpenCL/vendors/nvidia.icd

        # Tell the NVIDIA container runtime to expose all GPU capabilities (including compute/utility)
        ENV NVIDIA_VISIBLE_DEVICES all
        ENV NVIDIA_DRIVER_CAPABILITIES compute,utility,graphics,video

        COPY ./mods /mods
      pull: true # Always pull new base image
    pull_policy: build
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    environment:
      EULA: true
      TYPE: "FABRIC"
      VERSION: 1.21.10
      MEMORY: 8G
      MODRINTH_PROJECTS: |-
        fabric-api
        c2me
    ports:
      - "25565:25565/tcp"
    volumes:
      - ./data:/data
```

--------------------------------

### Example Docker Image Labels

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/troubleshooting.md

This is an example of the JSON output you can expect when inspecting Docker image labels. It includes metadata like authors, build date, and version.

```json
{
  "org.opencontainers.image.authors": "... <...@gmail.com>",
  "org.opencontainers.image.created": "2025-04-03T02:15:51.405Z",
  "org.opencontainers.image.description": "Docker image that provides a Minecraft Server for Java Edition that automatically downloads selected version at startup",
  "org.opencontainers.image.licenses": "Apache-2.0",
  "org.opencontainers.image.ref.name": "ubuntu",
  "org.opencontainers.image.revision": "d6897a649ecbc16b5fb2e1500e24b64ef80270a0",
  "org.opencontainers.image.source": "https://github.com/itzg/docker-minecraft-server",
  "org.opencontainers.image.title": "docker-minecraft-server",
  "org.opencontainers.image.url": "https://github.com/itzg/docker-minecraft-server",
  "org.opencontainers.image.version": "java21"
}
```

--------------------------------

### Multiple Source Directories for Plugins

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/index.md

This example shows how to specify multiple source directories for plugins using `COPY_PLUGINS_SRC`. It also demonstrates mounting these directories as read-only volumes.

```yaml
environment:
  # ...EULA, etc
  TYPE: PAPER
  # matches up to volumes declared below
  COPY_PLUGINS_SRC: /plugins-common,/plugins-local
volumes:
  - mc-data:/data
  # For example, reference a shared directory used by several projects
  - ../plugins-common:/plugins-common:ro
  # and add plugins unique to this project
  - ./plugins:/plugins-local:ro
```

--------------------------------

### Use a Custom Forge Installer URL

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/forge.md

Download a Forge installer from a custom URL by setting the FORGE_INSTALLER_URL environment variable. This also negates the need for VERSION and FORGE_VERSION.

```yaml
environment:
  TYPE: FORGE
  FORGE_INSTALLER_URL: http://your.custom.repo/forge-installer.jar
```

--------------------------------

### Example YAML configuration with multiple variable placeholders

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/interpolating.md

Shows a YAML configuration file with placeholders for database host, name, and password. These placeholders are intended to be replaced by environment variables during container startup.

```yaml
---
database:
  host: ${CFG_DB_HOST}
  name: ${CFG_DB_NAME}
  password: ${CFG_DB_PASSWORD}
```

--------------------------------

### Install Fabric API using Modrinth

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/fabric.md

Automatically install the Fabric API mod by listing it in MODRINTH_PROJECTS. This is often required by other Fabric mods.

```yaml
environment:
  TYPE: FABRIC
  MODRINTH_PROJECTS: |
    fabric-api
```

--------------------------------

### Run Quilt Server with Docker

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/quilt.md

Use this command to start a Quilt server. Ensure the TYPE environment variable is set to QUILT.

```shell
docker run -d --pull=always \
    -v /path/on/host:/data -e TYPE=QUILT \
    -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
```

--------------------------------

### Example TOML configuration with variable placeholder

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/interpolating.md

Demonstrates how to use a placeholder for a database password in a TOML configuration file. The placeholder `${CFG_DB_PASSWORD}` will be replaced by an environment variable.

```toml
[client]
password = "${CFG_DB_PASSWORD}"
```

--------------------------------

### VanillaTweaks Share Codes Example

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/world-data.md

Provide a comma-separated list of VanillaTweaks share codes for ResourcePacks, DataPacks, and CraftingTweaks.

```yaml
VANILLATWEAKS_SHARECODE: MGr52E,tF1zL2,LnEDwT
```

--------------------------------

### Run Fabric Server with Docker

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/fabric.md

Use this command to start a Fabric server. Ensure EULA is accepted and TYPE is set to FABRIC. Maps port 25565.

```shell
docker run -d --pull=always -e EULA=TRUE -e TYPE=FABRIC -p 25565:25565 itzg/minecraft-server
```

```yaml
environment:
  EULA: TRUE
  TYPE: FABRIC
```

--------------------------------

### Specify Quilt Loader and Installer Versions

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/quilt.md

To use specific versions of the Quilt loader and installer, set the QUILT_LOADER_VERSION and QUILT_INSTALLER_VERSION environment variables.

```shell
docker run -d --pull=always \
    -v /path/on/host:/data ... -e TYPE=QUILT \
    -e QUILT_LOADER_VERSION=0.16.0 \
    -e QUILT_INSTALLER_VERSION=0.4.1
```

--------------------------------

### Run CurseForge Server with Modpack

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/curseforge.md

Use this command to start a CurseForge server, specifying the modpack directly. Ensure the modpack zip file is accessible.

```shell
docker run -d --pull=always -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
```

--------------------------------

### Run Latest Stable Minecraft Server

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/index.md

Use this command to start a Docker container running the latest stable Minecraft server. Ensure EULA is accepted by setting EULA=TRUE.

```bash
docker run -d -it -p 25565:25565 -e EULA=TRUE itzg/minecraft-server
```

--------------------------------

### Using Cardboard Plugins with Fabric

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/index.md

This example demonstrates how to configure the server to use Cardboard plugins with Fabric. Set the TYPE to FABRIC, list the necessary Modrinth projects, and enable plugin synchronization.

```yaml
environment:
  EULA: "TRUE"
  TYPE: "FABRIC"
  MODRINTH_PROJECTS: |
    fabric-api
    cardboard
  USES_PLUGINS: true
```

--------------------------------

### Add Packages to Base Image with Dockerfile

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/building.md

Use an inline Dockerfile to extend the base image with additional packages. This example adds webp support.

```yaml
services:
  mc:
    build:
      context: .
      dockerfile_inline: |
        FROM itzg/minecraft-server:latest

        RUN apt-get update && apt-get install -y \
            webp \
            && rm -rf /var/lib/apt/lists/*
      pull: true # Always pull new base image
    pull_policy: build
    restart: unless-stopped
    environment:
      EULA: true
    ports:
      - "25565:25565/tcp"
    volumes:
      - ./data:/data
```

--------------------------------

### Enable Initial Datapacks

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/server-properties.md

Set the INITIAL_ENABLED_PACKS environment variable to a comma-separated list of datapack names to enable them before initial world creation. Example: "update_1_20,bundle".

```text
INITIAL_ENABLED_PACKS
```

--------------------------------

### Connect to WebSocket Console with Password

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/sending-commands/websocket.md

Example of establishing a WebSocket connection to the console, including the required protocol and password in the headers. Ensure 'mc-server-runner-ws-v1' is the first element and the password is the second.

```javascript
let socket = new WebSocket("http://localhost:80/websocket", ["mc-server-runner-ws-v1", "rcon-password"]);
```

--------------------------------

### Custom Server JAR Execution with Quotes

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/others.md

This example demonstrates how to properly quote the CUSTOM_JAR_EXEC argument when using docker run, as it contains spaces.

```shell
-e CUSTOM_JAR_EXEC="-cp worldedit.jar:Carpet-Server.jar net.minecraft.server.MinecraftServer"
```

--------------------------------

### Run Folia Server with Docker

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/paper.md

Use this command to start a Folia server container. Ensure you map the data volume and expose the correct port. Set EULA to TRUE to accept the Minecraft EULA.

```shell
docker run -d --pull=always \
    -v /path/on/host:/data -e TYPE=FOLIA \
    -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
```

--------------------------------

### Install FTB Modpack

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/ftb.md

Use this command to run the latest version of an FTB modpack. Ensure the FTB_MODPACK_ID environment variable is set to the correct modpack ID.

```shell
docker run -d --pull=always -v /path/on/host:/data \
    -e EULA=TRUE -e TYPE=FTBA \
    -e FTB_MODPACK_ID=31 -p 25565:25565 \
    itzg/minecraft-server:java8-multiarch
```

--------------------------------

### Build Image with Alternate Java Base

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/building.md

Specify an alternate Java base image using the `BASE_IMAGE` build argument. This example uses GraalVM CE with Java 11.

```shell
docker build --build-arg BASE_IMAGE=ghcr.io/graalvm/graalvm-ce:ol8-java11 -t IMG_PREFIX/minecraft-server:java11-graalvm .
```

--------------------------------

### Automatic Version Determination Example

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/modrinth.md

Sets the Minecraft version based on the compatibility of all listed projects. If 'griefprevention' is only compatible up to 1.21.7 while others support 1.21.8, the 'VERSION' will be set to 1.21.7.

```yaml
        MODRINTH_PROJECTS: |
          viaversion
          viabackwards
          griefprevention
          discordsrv
        VERSION_FROM_MODRINTH_PROJECTS: true
```

--------------------------------

### Install Modpack with docker run

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/index.md

Use the MODPACK environment variable to specify the URL or container path of a zip file containing mods or plugins for Forge, Fabric, or Bukkit/Spigot servers.

```shell
docker run -d -e MODPACK=http://www.example.com/mods/modpack.zip ...
```

--------------------------------

### Multi-line MOTD Configuration

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/server-properties.md

Illustrates how to configure a multi-line MOTD using environment variables. Supports newline characters within the string for docker run and compose file setups.

```shell
-e MOTD="Line one\nLine two"
```

```shell
-e MOTD=$'Line one\nLine two'
```

```yaml
MOTD: |
  line one
  line two
```

```yaml
MOTD: "line one\nline two"
```

--------------------------------

### Lazymc Proxy Setup

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/examples.md

This configuration snippet is part of setting up Lazymc with the minecraft container. It highlights the need for a static IP and a custom Docker network to ensure proper functionality.

```yaml
# Lazymc requires that the minecraft server have a static IP.
#
# To ensure that our servers have a static IP we need to create
# a network for our services to use.
#
# By default, Docker uses 172.17.0.0/16 subnet range.
# So we need to create a new network in a different subnet
# See the readme for more information.
#
# Please ensure that the subnet falls within the private CIDRs:
# https://datatracker.ietf.org/doc/html/rfc1918#section-3
#
```

--------------------------------

### Run Local Documentation Server

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/contributing/docs.md

Use this command to build and serve the documentation locally for real-time preview during development. Access the live rendering at http://localhost:8000.

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

--------------------------------

### Load Mods/Plugins from a File

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/index.md

Loads mods and plugins from a text file specified by MODS_FILE or PLUGINS_FILE. Each line in the file should contain a URL or container path to a mod/plugin. Blank lines and lines starting with '#' are ignored.

```text
https://edge.forgecdn.net/files/2965/233/Bookshelf-1.15.2-5.6.40.jar
https://edge.forgecdn.net/files/2926/27/ProgressiveBosses-2.1.5-mc1.15.2.jar
# This and next line are ignored
#https://edge.forgecdn.net/files/3248/905/goblintraders-1.3.1-1.15.2.jar
https://edge.forgecdn.net/files/3272/32/jei-1.15.2-6.0.3.16.jar
https://edge.forgecdn.net/files/2871/647/ToastControl-1.15.2-3.0.1.jar
```

--------------------------------

### Skip GTNH update check

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/gtnh.md

To prevent update checks and server installation from running after initial setup, set SKIP_GTNH_UPDATE_CHECK to true. This is useful for managing updates manually.

```shell
SKIP_GTNH_UPDATE_CHECK=true
```

--------------------------------

### Execute RCON commands on server start

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/auto-rcon-commands.md

Use the RCON_CMDS_STARTUP environment variable to define commands that run when the Minecraft server begins. YAML's block style indicator `|-` is recommended for multi-line commands.

```yaml
      RCON_CMDS_STARTUP:  |-
        gamerule doFireTick false
        pregen start 200
```

--------------------------------

### Force Forge Reinstall

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/forge.md

If Forge installation fails, temporarily set FORGE_FORCE_REINSTALL to "true" to force a reinstallation. Remember to remove this variable after the server starts successfully.

```yaml
environment:
  FORGE_FORCE_REINSTALL: "true"
```

--------------------------------

### Java 8 Requirement Example

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/versions/java.md

This error suggests that your server requires Java 8, likely due to Forge versions less than 1.18. Use a `java8-multiarch` or other Java 8 tagged image.

```java
Caused by: java.lang.ClassCastException: class jdk.internal.loader.ClassLoaders$AppClassLoader 
   cannot be cast to class java.net.URLClassLoader
```

--------------------------------

### Enable Setup-Only Mode

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/misc-options.md

Set the SETUP_ONLY environment variable to 'true' to have the image set up Minecraft server files and then stop before launching the server process. This is useful for host-attached data directories.

```bash
export SETUP_ONLY=true
```

--------------------------------

### Run a NeoForge Server with Docker

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/forge.md

Configure a NeoForge server by setting TYPE to NEOFORGE. Specify the Minecraft version with VERSION and the NeoForge version with NEOFORGE_VERSION.

```shell
docker run -e TYPE=NEOFORGE -e VERSION=1.20.1 -e NEOFORGE_VERSION=47.1.79 ...
```

```yaml
environment:
  TYPE: NEOFORGE
  VERSION: "1.20.4"
  NEOFORGE_VERSION: "beta"
```

--------------------------------

### Build Go Base Tools with GoReleaser

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/contributing/development.md

Use `goreleaser` to build Go base tools for release. The `--snapshot` flag builds from the current state, and `--clean` ensures a clean build environment.

```shell
goreleaser release --snapshot --clean
```

--------------------------------

### Download Extra Configurations (Multi-line)

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/misc-options.md

Use the DOWNLOAD_EXTRA_CONFIGS environment variable to specify a multi-line list of plugin configurations to download. Each line should specify the destination path relative to /data/ and the URL.

```yaml
environment:
  DOWNLOAD_EXTRA_CONFIGS: |
    plugins/WorldEdit<https://raw.githubusercontent.com/EngineHub/WorldEdit/refs/heads/version/7.3.x/worldedit-bukkit/src/main/resources/defaults/config.yml
    plugins/EssentialsX<https://raw.githubusercontent.com/EssentialsX/Essentials/refs/heads/2.x/Essentials/src/main/resources/config.yml
```

--------------------------------

### Disable Modpack Start Script

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/curseforge.md

Add `-e USE_MODPACK_START_SCRIPT=false` to bypass buggy or complex start scripts within certain modpacks, using the image's standard server-starting logic instead.

```shell
-e USE_MODPACK_START_SCRIPT=false
```

--------------------------------

### Remove Old Mods/Plugins Before Installing Modpack

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/index.md

Enables the removal of all existing mods and plugins from the 'mods' or 'plugins' directory before installing a new modpack. This is useful for upgrading mods/plugins from a downloaded zip file.

```shell
docker run -d -e REMOVE_OLD_MODS=TRUE -e MODPACK=http://www.example.com/mods/modpack.zip ...
```

--------------------------------

### PaperMC Experimental Build Tip

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/paper.md

If encountering 'No build found for version X with channel 'default'', set PAPER_CHANNEL to 'experimental' to allow selection of experimental builds.

```text
No build found for version 1.21 with channel 'default'
```

--------------------------------

### Download Extra Configurations (Single-line)

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/misc-options.md

Alternatively, specify configurations for DOWNLOAD_EXTRA_CONFIGS on a single line, separating entries with commas. Each entry follows the path<URL format.

```yaml
environment:
  DOWNLOAD_EXTRA_CONFIGS: "plugins/WorldEdit<https://example.com/worldedit.yml,config<https://example.com/another.yml"
```

--------------------------------

### Pin Modpack Version with File URL

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/auto-curseforge.md

Use CF_PAGE_URL to specify the exact URL of the desired modpack file for installation.

```yaml
CF_PAGE_URL: https://www.curseforge.com/minecraft/modpacks/all-the-mods-8/files/4248390
```

--------------------------------

### Build Spigot from Source

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/bukkit-spigot.md

Enable building Spigot from source by setting the BUILD_FROM_SOURCE environment variable to 'true'. This is useful for development or using unreleased versions.

```bash
docker run ... -e BUILD_FROM_SOURCE=true ...
```

--------------------------------

### Pin Modpack Version with File ID

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/auto-curseforge.md

Use CF_FILE_ID to specify the numerical file ID of the desired modpack file for installation.

```yaml
CF_SLUG: all-the-mods-8
CF_FILE_ID: "4248390"
```

--------------------------------

### Docker Run: Using CF_SLUG

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/auto-curseforge.md

Use `docker run` to install a modpack by providing its CurseForge slug with the CF_SLUG environment variable.

```shell
docker run -e CF_API_KEY=${CF_API_KEY} -e TYPE=AUTO_CURSEFORGE -e CF_SLUG=all-the-mods-8
```

--------------------------------

### Docker Compose: Using CF_SLUG

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/auto-curseforge.md

Configure docker compose to install a modpack using its CurseForge slug identifier via CF_SLUG.

```yaml
environment:
  # ...
  MODPACK_PLATFORM: AUTO_CURSEFORGE
  # allocate from https://console.curseforge.com/ and set in .env file
  CF_API_KEY: ${CF_API_KEY}
  CF_SLUG: all-the-mods-8
```

--------------------------------

### Docker Run: Using CF_PAGE_URL

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/auto-curseforge.md

Use `docker run` to automatically install a modpack by specifying its CurseForge page URL with CF_PAGE_URL.

```shell
docker run -e CF_API_KEY=${CF_API_KEY} -e TYPE=AUTO_CURSEFORGE -e CF_PAGE_URL=https://www.curseforge.com/minecraft/modpacks/all-the-mods-8
```

--------------------------------

### Ignoring Missing Modpack Files

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/modrinth-modpacks.md

Specify files to ignore when they are missing after installation to prevent re-installation. Useful for mods that clean up temporary files.

```yaml
environment:
  MODRINTH_IGNORE_MISSING_FILES: |
    config/mcinstanceloader/pack.mcinstance
    mods/*.jar
```

--------------------------------

### Use Java 8 Image with Docker Run

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/versions/java.md

Run the Minecraft server using the Java 8 image. Ensure the EULA is accepted by setting the EULA=true environment variable.

```bash
docker run -it -e EULA=true itzg/minecraft-server:java8
```

--------------------------------

### Docker Compose: Using CF_PAGE_URL

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/auto-curseforge.md

Configure docker compose to automatically install a modpack by providing its CurseForge page URL via CF_PAGE_URL.

```yaml
environment:
  # ...
  MODPACK_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
```

--------------------------------

### Build Multi-Architecture Image with Buildx

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/building.md

Build a multi-architecture image for various platforms (arm64, arm/v7, amd64) and push it to a repository using Docker Buildx.

```shell
docker buildx build --platform=linux/arm64 --platform=linux/arm/v7 --platform=linux/amd64 --tag IMG_PREFIX/minecraft-server --push .
```

--------------------------------

### Set Timezone using TZ variable

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/misc-options.md

Configures the server's timezone by setting the TZ environment variable. Example uses Europe/London.

```bash
-e TZ=Europe/London
```

--------------------------------

### Load Multi-Architecture Image Locally with Buildx

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/building.md

Build a multi-architecture image and load it into the local Docker daemon using Docker Buildx. This is for local use when pushing to a remote repository is not desired.

```shell
docker buildx build --tag IMG_PREFIX/minecraft-server --load .
```

--------------------------------

### Force World Overwrite

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/world-data.md

Set FORCE_WORLD_COPY to TRUE to ensure the world is downloaded or copied on every server start, overwriting any existing world data.

```bash
docker run -d -e FORCE_WORLD_COPY=TRUE ...
```

--------------------------------

### Configure Modrinth Projects

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/modrinth.md

Set the MODRINTH_PROJECTS environment variable to a comma or newline-separated list of Modrinth projects to download. Supports various formats for specifying projects, versions, and release types.

```bash
MODRINTH_PROJECTS=fabric-api
```

```bash
MODRINTH_PROJECTS=fabric-api:bQZpGIz0
fabric-api:0.119.2+1.21.4
```

```bash
MODRINTH_PROJECTS=fabric-api:beta
```

```bash
MODRINTH_PROJECTS=P7dR8mSH
```

```bash
MODRINTH_PROJECTS=datapack:terralith
```

```bash
MODRINTH_PROJECTS=datapack:terralith:2.5.5
```

```bash
MODRINTH_PROJECTS=fabric:fabric-api
fabric:fabric-api:bQZpGIz0
```

```bash
MODRINTH_PROJECTS=@/path/to/modrinth-mods.txt
```

--------------------------------

### Run Bukkit/Spigot Server Type

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/bukkit-spigot.md

Set the TYPE environment variable to 'SPIGOT' or 'BUKKIT' to run the respective server type. This is the primary method for selecting the server software.

```bash
docker run ... -e TYPE=SPIGOT ...
```

```yaml
environment:
  ...
  TYPE: SPIGOT
```

--------------------------------

### Ignore Missing Files with CF_IGNORE_MISSING_FILES

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/auto-curseforge.md

Prevent the installer from re-installing mods due to missing files. Provide a comma, newline-delimited list, or a file globbing pattern.

```yaml
        CF_IGNORE_MISSING_FILES: |
          mods/gregtech-2.6.2-beta.jar
          mods/*.jar
```

--------------------------------

### Configure PaperMC Server

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/paper.md

Set TYPE to PAPER to use PaperMC. Optionally specify VERSION, PAPER_BUILD, or PAPER_CHANNEL for specific builds. Use PAPER_DOWNLOAD_URL to override the download source.

```shell
docker run ... -e TYPE=PAPER ...
```

```shell
docker run ... -e TYPE=PAPER -e VERSION=1.20.6 ...
```

```shell
docker run ... -e TYPE=PAPER -e VERSION=1.20.6 -e PAPER_BUILD=140 ...
```

```shell
docker run ... -e TYPE=PAPER -e PAPER_CHANNEL=experimental ...
```

--------------------------------

### Run Server with Local mc-image-helper Mount

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/contributing/development.md

Run the Minecraft server container, mounting a local development copy of mc-image-helper into the container. This allows testing modifications to the helper tool.

```shell
docker run -it --rm \
  -v /path/to/mc-image-helper/build/install/mc-image-helper:/usr/share/mc-image-helper \
  -e EULA=true \
  itzg/minecraft-server
```

--------------------------------

### Java 17+ Java arguments for GTNH

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/gtnh.md

When using Java 17 or later, the server starts with these specific Java arguments. These are optimized for newer Java versions and the GTNH modpack.

```java
-Dfml.readTimeout=180 @java9args.txt -jar lwjgl3ify-forgePatches.jar
```

--------------------------------

### Java 21 Error Example

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/versions/java.md

This error indicates that a mod requires Java 17 and is incompatible with Java 21. Use a Java 17 tagged image if this error occurs.

```java
Caused by: org.spongepowered.asm.mixin.throwables.ClassMetadataNotFoundException: java.util.List
	at MC-BOOTSTRAP/org.spongepowered.mixin/org.spongepowered.asm.mixin.transformer.MixinPreProcessorStandard.transformMethod(MixinPreProcessorStandard.java:754)
```

--------------------------------

### Set Server Icon via URL

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/server-properties.md

Configure the server icon by providing a URL to the image. The image will be downloaded, scaled, and converted.

```bash
docker run -d -e ICON=http://..../some/image.png ...
```

--------------------------------

### Configure Purpur Server

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/paper.md

Set TYPE to PURPUR to use Purpur. Use PURPUR_BUILD to specify a build number. FORCE_REDOWNLOAD, USE_FLARE_FLAGS, and PURPUR_DOWNLOAD_URL are additional configuration options.

```shell
-e TYPE=PURPUR
```

--------------------------------

### Pass Extra JVM Options

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/jvm-options.md

Use the JVM_OPTS environment variable to pass general JVM arguments to the Minecraft Server. Arguments are space-delimited.

```bash
docker run ... -e JVM_OPTS="-XsomeJVMOption -DpropName=value" ...
```

--------------------------------

### Execute RCON commands on first client connect

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/auto-rcon-commands.md

Use RCON_CMDS_FIRST_CONNECT to specify commands that should run only when the very first client connects to the server after startup.

```yaml
      RCON_CMDS_FIRST_CONNECT: |- 
        pregen stop
```

--------------------------------

### Specify Fabric Loader and Launcher Versions

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/fabric.md

Set FABRIC_LAUNCHER_VERSION and FABRIC_LOADER_VERSION to use specific versions of the Fabric components. Useful for compatibility with older mods or specific server setups.

```shell
docker run -d ... \
    -e TYPE=FABRIC \
    -e FABRIC_LAUNCHER_VERSION=0.10.2 \
    -e FABRIC_LOADER_VERSION=0.13.1
```

```yaml
environment:
  EULA: TRUE
  TYPE: FABRIC
  FABRIC_LAUNCHER_VERSION: 0.10.2
  FABRIC_LOADER_VERSION: 0.13.1
```

--------------------------------

### Configure Custom Worlds Directory

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/world-data.md

Use the EXTRA_ARGS environment variable to pass arguments to the server jar, such as --world-dir for custom Multiverse plugin world directories. Aliases like -W or --universe can also be used.

```bash
docker run -d -e EXTRA_ARGS='--world-dir ./worlds/'
```

--------------------------------

### Set Game Mode to Creative using Docker Run

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/server-properties.md

Run the Minecraft server in creative mode by setting the MODE environment variable.

```bash
docker run -d -e MODE=creative ...
```

--------------------------------

### Generate Release Notes Content

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/contributing/development.md

Generate the bulk of release notes content by logging git commits between two versions. This command excludes commits starting with 'ci:', 'misc:', or 'docs:'.

```shell
git log --invert-grep --grep "^ci:" --grep "^misc:" --grep "^docs:" --pretty="* %s" 1.1.0..1.2.0
```

--------------------------------

### Enable Proxy Protocol Support

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/misc/autopause-autostop/autostop.md

Set this environment variable to true if you are using a proxy like HAProxy or Fly.io and want to enable PROXY Protocol support. This is necessary for Autostop to monitor the server correctly in such configurations.

```bash
USES_PROXY_PROTOCOL=true
```

--------------------------------

### Exclude Mods using Ant-style Paths (Single Line)

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/mod-platforms/modrinth-modpacks.md

Use this environment variable to specify Ant-style paths for mods to be excluded from overrides. This example excludes specific JAR files.

```yaml
MODRINTH_OVERRIDES_EXCLUSIONS: mods/NekosEnchantedBooks-*.jar,mods/citresewn-*.jar
```

--------------------------------

### Auto-download Plugins using SPIGET_RESOURCES

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/spiget.md

Set the SPIGET_RESOURCES environment variable with a comma-separated list of SpigotMC resource IDs to automatically download plugins. Resources are automatically expanded or placed in the plugins directory.

```bash
-e SPIGET_RESOURCES=28140,34315
```

--------------------------------

### Configure Existing Whitelist File Behavior

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/server-properties.md

Set the EXISTING_WHITELIST_FILE environment variable to control how the server handles an existing whitelist file. Options include SKIP, SYNCHRONIZE, MERGE, and SYNC_FILE_MERGE_LIST (default).

```text
SKIP
```

```text
SYNCHRONIZE
```

```text
MERGE
```

```text
SYNC_FILE_MERGE_LIST
```

--------------------------------

### Send Command via mc-send-to-console

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/sending-commands/commands.md

When RCON is disabled, use this command to send Minecraft commands by setting CREATE_CONSOLE_IN_PIPE to true and passing commands to mc-send-to-console. The user 1000 is specified for this example.

```shell
docker exec --user 1000 mc mc-send-to-console op player
```

--------------------------------

### Specify Forge Version and Minecraft Version

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/types-and-platforms/server-types/forge.md

Control the specific Forge and Minecraft versions by setting VERSION and FORGE_VERSION environment variables. 'latest' can be used for FORGE_VERSION to get the latest available.

```shell
docker run -e TYPE=FORGE -e VERSION=1.12.2 -e FORGE_VERSION=14.23.5.2854 ...
```

```yaml
environment:
  TYPE: FORGE
  VERSION: "1.12.2"
  FORGE_VERSION: "14.23.5.2854"
```

--------------------------------

### Set Initial and Max JVM Memory with INIT_MEMORY and MAX_MEMORY

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/jvm-options.md

Independently set initial and maximum JVM heap sizes using INIT_MEMORY and MAX_MEMORY environment variables. Supports units like G, M, K.

```bash
-e INIT_MEMORY=1G -e MAX_MEMORY=4G
```

--------------------------------

### Configure HTTP Proxy

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/misc-options.md

Sets up an HTTP/HTTPS proxy for the server. The proxy host and port can be specified separately.

```bash
-e PROXY=host:port
```

--------------------------------

### Using Placeholders in Compose File

Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/configuration/server-properties.md

Demonstrates how to use environment variables with placeholders for dynamic MOTD and level names in a Docker Compose file.

```yaml
MOTD: Running %MODPACK_NAME% version %env:MODPACK_VERSION%
LEVEL: world-%date:yyyy-MM-dd%
```