isopods/minecraft

Overview

This Docker image provides a secure, distroless Fabric Minecraft server, fully compatible with vanilla clients by default (unless additional mods are installed). It features only the Java Runtime Environment (JRE) from the OpenJDK project, ensuring a lightweight and secure setup. The image is built on the https://hub.docker.com/r/ubuntu/jre base image.

Running Container

It is recommended to use https://github.com/noahsub/Isopod to setup the container.

By using this image, you acknowledge and agree to the Minecraft End User License Agreement (EULA). To confirm your acceptance, you must set the EULA environment variable to true; otherwise, the server will not start.

Since this image is distroless, it lacks a shell. If the EULA variable is not set, you must manually modify the /server/eula.txt file in the container's mounted volume. Additionally, administrator users (ops) must be specified during the initial docker run command, as console access is unavailable. This means you cannot simply execute /op mc_username once the server is running.

Template

bash
docker run -d \
  --name minecraft_server \
  -p <host_port>:25565 \
  -e EULA=true \
  -e ADMINS="<mc_username>" \
  -e <KEY>=<value> \
  -v <volume_name>:/server \
  isopods/minecraft:<mc_version>

Example

bash
docker run -d \
  --name minecraft_server \
  -p 25565:25565 \
  -e EULA=true \
  -e ADMINS="mc_username" \
  -e XMS=1500M \
  -e XMX=8G \
  -e BONUS_CHEST=true \
  -v minecraft_volume:/server \
  isopods/minecraft:1.21.5

Configuration

The Minecraft server image provides extensive configuration options through environment variables. Simply append -e KEY=value to the docker run command to customize your server setup.

JVM Options

• XMS (Initial Memory Allocation): Sets the initial heap size for the JVM.
  • Example: -e XMS=1G for 1GB of initial memory.
• XMX (Maximum Memory Allocation): Sets the maximum heap size for the JVM.
  • Example: -e XMX=2G for 2GB of maximum memory.
• JVM_ARGS: Additional JVM arguments can be specified here.
  • Example: -e JVM_ARGS="-XX:+UseG1GC -XX:+UseStringDeduplication".

Server Properties

Server properties can be customized using environment variables that correspond to the property names in server.properties for the specified Minecraft version. It is important to note that certain characters in the original property names are replaced with underscores (_) in the environment variables. Specifically:

• Spaces ( ``), periods (.), and hyphens () are replaced with underscores (_).

For example, some configuration options include:

• MOTD (Message of the Day): Custom server greeting message.
  • Example: -e MOTD="Welcome to My Minecraft Server"
• PVP (Player vs Player): Enable or disable PvP.
  • Example: -e PVP=true
• DIFFICULTY: Set the game difficulty.
  • Example: -e DIFFICULTY=hard

Server Options

The image also provides options for additional server arguments:

• BONUS_CHEST: Enable bonus chest.
  • Example: -e BONUS_CHEST=true
• DEMO: Run the server in demo mode.
  • Example: -e DEMO=true
• FORCE_UPGRADE: Force upgrade of the world.
  • Example: -e FORCE_UPGRADE=true
• ERASE_CACHE: Clear the server cache.
  • Example: -e ERASE_CACHE=true
• SAFE_MODE: Start the server in safe mode.
  • Example: -e SAFE_MODE=true
• JFR_PROFILE: Enable Java Flight Recorder profiling.
  • Example: -e JFR_PROFILE=true
• PORT: Specify a custom server port.
  • Example: -e PORT=25565
• SERVER_ID: Set a custom server ID.
  • Example: -e SERVER_ID=my_server_id
• SINGLEPLAYER: Run in singleplayer mode.
  • Example: -e SINGLEPLAYER=true
• UNIVERSE: Set a custom universe path.
  • Example: -e UNIVERSE=/data/universe
• WORLD: Set the world directory.
  • Example: -e WORLD=/data/world
• INIT_SETTINGS: Load initialization settings from a file.
  • Example: -e INIT_SETTINGS=/data/init.yml
• HELP: Display help information.

Admin Configuration

• ADMINS: Specify server operators (admins) using usernames separated by spaces.
  • Example: -e ADMINS="user1 user2"
  • The system automatically retrieves the UUIDs of these users and writes them to ops.json.

EULA Agreement

• EULA: Indicates your agreement with the Minecraft EULA.
  • Example: -e EULA=true
  • If not set to true, the server will not start.

Advanced Usage

The server configuration script automatically generates the server.properties and ops.json files based on the provided environment variables. If these files already exist, they will not be overwritten, ensuring that your settings are preserved between container restarts.