DOCSEARCHbyAlgolia
Submit Docs

itzg/minecraft-server Docker Image

repository·master·Indexed 11 days ago

https://github.com/itzg/docker-minecraft-server

A Docker-based solution for deploying and managing Minecraft Java Edition servers. It features extensive configuration via environment variables, automated mod/plugin management, and support for various server types (Paper, Purpur, Pufferfish) and modpack providers like CurseForge. The project includes guides for multi-project Docker Compose architectures, Podman Quadlets, and Kubernetes deployments using Kustomize.

Tokens
45.7K
Snippets
170
Records
228
Agent score
96%

What's inside itzg/minecraft-server

  1. Overview of itzg/docker-minecraft-server

    master

    The itzg/docker-minecraft-server project provides a Docker image for running Minecraft Java Edition servers. It allows for highly configurable server deployments using environment variables, automated management of mods and plugins, and support for various server types and modpack providers.

    Key Capabilities:

    • Run different versions of Minecraft Java Edition.
    • Use various server types and platforms.
    • Configure server properties via container environment variables.
    • Automate mod and plugin downloads and cleanup.
    • Use various modpack providers/platforms.

    Note on Editions: This image natively supports Java Edition. For Bedrock Edition, you should use itzg/minecraft-bedrock-server or follow specific configuration steps to add Bedrock compatibility to a Java server.

  2. Explore related Minecraft Docker projects

    master

    The itzg/docker-minecraft-server ecosystem includes several specialized tools and images for managing Minecraft environments:

    • Bedrock Support: Use itzg/minecraft-bedrock-server for running Minecraft Bedrock Edition servers.
    • Proxy & Routing:
      • mc-router: A lightweight multiplexer/proxy for Java servers (available as a standalone app or Docker image).
      • itzg/mc-proxy: A Docker image running Bungeecord, Velocity, or Waterfall proxies.
    • Management & Utilities:
      • itzg/mc-backup: A side-car container designed to backup world data.
      • rcon-cli: A CLI tool bundled with the main image for RCON endpoint access.
      • mc-monitor: A bundled tool for health checks and metrics (Prometheus exporter or Telegraf data source).
      • mc-image-helper: A bundled tool for complex, reusable preparation operations.
      • itzg/rcon: A Docker image for rcon-web-admin to provide a web-based RCON interface.

  3. Use placeholders in server property environment variables

    master

    When defining server properties via environment variables, you can use DOS-style placeholders (%VAR%) which are processed when the server.properties file is updated. This allows for dynamic configuration based on environment state or time.

    Supported Placeholders

    • %VAR% or %env:VAR%: Replaces the placeholder with the resolved value of the environment variable VAR.
    • %date:FMT%: Formats the current date/time using a string processed by Java's DateTimeFormatter.

    Available Variables for Placeholders

    • Standard Variables: Any declared or resolved environment variable.
    • Version Info: VERSION (the resolved version) and DECLARED_VERSION (the original version string like LATEST or SNAPSHOT).
    • Modpacks: If using Modrinth or Auto CurseForge, %MODPACK_NAME% and %MODPACK_VERSION% are available.

    !!! warning Placeholders are not supported when manually managing the server.properties file.

    # Example usage in a compose file
environment:
  MOTD: "Running %MODPACK_NAME% version %env:MODPACK_VERSION%"
  LEVEL: "world-%date:yyyy-MM-dd%"

  4. How environment variable reloading works with Packwiz

    master

    When using Packwiz, the container supports reloading environment variables from a .env file provided within the pack.

    If you use LOAD_ENV_FROM_FILE and the pack contains a .env file, that file is re-loaded immediately after the packwiz installer completes. This ensures that any freshly downloaded values are applied to the subsequent startup stages.

    Limitations:

    • TYPE and VERSION are resolved before the deployment is dispatched. Therefore, a .env file provided via Packwiz cannot change these values.
    • To change TYPE or VERSION via a pack, use LOAD_ENV_FROM_GENERIC_PACK or LOAD_ENV_FROM_ARCHIVE instead.

  5. Use OCI registries for Generic Packs

    master

    You can reference modpacks stored as OCI artifacts in a container registry by prefixing the entry with oci://. This supports tags (e.g., :latest) or immutable digests (e.g., @sha256:...).

    • Authentication: For private registries, set GENERIC_PACKS_OCI_AUTH_FILE to the path of a registry login file (e.g., auth.json from docker login). If unset, it defaults to ~/.config/containers/auth.json or ~/.docker/config.json.
    • Caching: Layers are cached under /data/packs/oci to avoid redundant downloads.
    • Requirements: The artifact must be a valid Minecraft modpack artifact (type application/vnd.itzg.minecraft.modpack.v1+json).
    GENERIC_PACKS=oci://ghcr.io/itzg/oci-modpack-template/tech:latest,oci://ghcr.io/itzg/oci-modpack-template/magic:latest
GENERIC_PACKS_OCI_AUTH_FILE=/run/secrets/registry-auth.json

  6. Configure Minecraft version and type

    master

    By default, the image downloads the latest stable "vanilla" Minecraft: Java Edition server. You can customize the server by configuring the following environment variables:

    • VERSION: Specifies the specific Minecraft version to run.
    • TYPE: Specifies the server type (e.g., vanilla, forge, fabric, etc.).

  7. Automatically determine Minecraft version from Modrinth projects

    master

    By setting VERSION_FROM_MODRINTH_PROJECTS to true, the Minecraft VERSION will be automatically determined by finding the most recent version of Minecraft supported by all projects listed in MODRINTH_PROJECTS.

    MODRINTH_PROJECTS: |
  viaversion
  viabackwards
  griefprevention
  discordsrv
VERSION_FROM_MODRINTH_PROJECTS: true

  9. CurseForge dependency detection limitations

    master
    The CurseForge file processing system can detect if a required dependency is missing from your CURSEFORGE_FILES list. However, it cannot automatically resolve or download those missing dependencies. This is because CurseForge metadata typically only provides the mod ID and does not specify the exact file version or ID required by the parent mod. You must explicitly list all required dependencies in your CURSEFORGE_FILES declaration.

  10. Use Auto CurseForge to manage modpacks

    master

    To automatically install and manage a CurseForge modpack (including automatic upgrades and cleanup of unused files), set MODPACK_PLATFORM, MOD_PLATFORM, or TYPE to AUTO_CURSEFORGE.

    Important Considerations:

    • The appropriate mod loader (Forge/Fabric) version is automatically installed based on the modpack declaration.
    • World data is never automatically removed during cleanup.
    • Ensure you use a Java version compatible with the modpack.
    • Most modpacks require significant memory; it is recommended to set MEMORY to at least 4G.
    environment:
  MODPACK_PLATFORM: AUTO_CURSEFORGE

  11. Mark Modrinth projects as optional

    master

    You can append a ? to a project slug or ID to mark it as optional. If a compatible version cannot be found, the container will log a warning and continue startup instead of failing. This is ideal for server-side tools like map renderers (Pl3xmap, BlueMap) or performance mods that may lag behind Minecraft updates.

    When combined with VERSION_FROM_MODRINTH_PROJECTS: true, optional projects are excluded from the version calculation, meaning an outdated optional mod will never block a Minecraft version upgrade.

    MODRINTH_PROJECTS: |
  fabric-api
  lithium
  pl3xmap? 
  bluemap?:beta
VERSION_FROM_MODRINTH_PROJECTS: true

  12. How healthchecks work in the Minecraft server image

    master

    The image includes mc-monitor and uses its status command to perform continuous health checks. The health status is visible in the STATUS column of docker ps (e.g., Up 41 seconds (healthy)).

    To check the health status programmatically in a script, use docker container inspect with a format template.

    docker container inspect -f "{{.State.Health.Status}}" mc
# Output: healthy