search

itzg / docker-bungeecord

A BungeeCord server to use in conjunction with itzg/minecraft-server
Apache License 2.0
188 stars 62 forks source link
bungeecord docker-image minecraft-server

readme

This is a Docker image that provides a choice of Minecraft proxies, such as BungeeCord and Velocity. It is intended to be used in combination with itzg/minecraft-server containers.

Build and Publish

Using with itzg/minecraft-server image

When using with the server image itzg/minecraft-server you can disable online mode, which is required by bungeecord, by setting ONLINE_MODE=FALSE, such as

docker run ... -e ONLINE_MODE=FALSE itzg/minecraft-server

The following is an example that can be started with docker compose up -d:

services:
  mc:
    image: itzg/minecraft-server
    environment:
      EULA: "TRUE"
      ONLINE_MODE: "FALSE"
    volumes:
      - mc-data:/data
  proxy:
    image: itzg/mc-proxy
    environment:
      BUNGEE_JAR_REVISION: "1"
      CFG_MOTD: Powered by Docker
      REPLACE_ENV_VARIABLES: "true"
    ports:
      - "25565:25577"
    volumes:
      - ./config.yml:/config/config.yml
      - proxy-data:/server

volumes:
  mc-data:
  proxy-data:

Healthcheck

This image contains mc-monitor and uses its status command to continually check on the container's. That can be observed from the STATUS column of docker ps

CONTAINER ID    IMAGE    COMMAND                         CREATED           STATUS                     PORTS                       NAMES
b418af073764    mc       "/usr/bin/run-bungeecord.sh"    43 seconds ago    Up 41 seconds (healthy)    0.0.0.0:25577->25577/tcp    mc

You can also query the container's health in a script friendly way:

> docker container inspect -f "{{.State.Health.Status}}" mc
healthy

Environment Settings

Optional Environment Settings

Volumes

Ports

Java Versions

The following table shows the Java versions and CPU architectures supported by the image tags:

Tag Java Architectures
latest 17 amd64, arm64, armv7
java8 8 amd64, arm64, armv7
java11 11 amd64, arm64, armv7

Interacting with the server

RCON is enabled by default, so you can exec into the container to access the Bungeecord server console:

docker exec -i mc rcon-cli

Note: The -i is required for interactive use of rcon-cli.

To run a simple, one-shot command, such as stopping a Bungeecord server, pass the command as arguments to rcon-cli, such as:

docker exec mc rcon-cli en

The -i is not needed in this case.

In order to attach and interact with the Bungeecord server, add -it when starting the container, such as

docker run -d -it -p 25565:25577 --name mc itzg/mc-proxy

With that you can attach and interact at any time using

docker attach mc

and then Control-p Control-q to detach.

For remote access, configure your Docker daemon to use a tcp socket (such as -H tcp://0.0.0.0:2375) and attach from another machine:

docker -H $HOST:2375 attach mc

Unless you're on a home/private LAN, you should enable TLS access.

BungeeCord Configuration

BungeeCord Configuration Guide

Generic pack files

To install all the server content (jars, mods, plugins, configs, etc.) from a zip or tgz file, then set GENERIC_PACK to the container path or URL of the archive file.

If multiple generic packs need to be applied together, set GENERIC_PACKS instead, with a comma separated list of archive file paths and/or URLs to files.

To avoid repetition, each entry will be prefixed by the value of GENERIC_PACKS_PREFIX and suffixed by the value of GENERIC_PACKS_SUFFIX, both of which are optional. For example, the following variables

GENERIC_PACKS=configs-v9.0.1,mods-v4.3.6
GENERIC_PACKS_PREFIX=https://cdn.example.org/
GENERIC_PACKS_SUFFIX=.zip

would expand to https://cdn.example.org/configs-v9.0.1.zip,https://cdn.example.org/mods-v4.3.6.zip.

Replacing variables inside configs

Sometimes you have mods or plugins that require configuration information that is only available at runtime. For example if you need to configure a plugin to connect to a database, you don't want to include this information in your Git repository or Docker image. Or maybe you have some runtime information like the server name that needs to be set in your config files after the container starts.

For those cases there is the option to replace defined variables inside your configs with environment variables defined at container runtime.

If you set the environment variable REPLACE_ENV_VARIABLES to TRUE the startup script will go through all files inside your /server volume and replace variables that match your defined environment variables. Variables that you want to replace need to be declared as ${YOUR_VARIABLE}, which is common with shell scripting languages.

With REPLACE_ENV_VARIABLE_PREFIX you can define a prefix, where the default is CFG_, to only match predefined environment variables.

If you want to use a file for a value (such as when using Docker secrets) you can add suffix _FILE to your variable name (in run command). For example, ${CFG_PASSWORD_FILE} would be replaced with the contents of the file specified by the CFG_PASSWORD_FILE environment variable.

Here is a full example where we want to replace values inside a database.yml.


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

This is how your docker-compose.yml file could look like:

version: "3.8"
# Other docker-compose examples in /examples

services:
  proxy:
    image: itzg/mc-proxy
    ports:
      - "25577:25577"
    volumes:
      - "proxy:/server"
    environment:
      # enable env variable replacement
      REPLACE_ENV_VARIABLES: "TRUE"
      # define an optional prefix for your env variables you want to replace
      ENV_VARIABLE_PREFIX: "CFG_"
      # and here are the actual variables
      CFG_DB_HOST: "http://localhost:3306"
      CFG_DB_NAME: "minecraft"
      CFG_DB_PASSWORD_FILE: "/run/secrets/db_password"
    restart: always

volumes:
  proxy:

secrets:
  db_password:
    file: ./db_password

The content of db_password:

ug23u3bg39o-ogADSs

Patching existing files

JSON path based patches can be applied to one or more existing files by setting the variable PATCH_DEFINITIONS to the path of a directory that contains one or more patch definition json files or a patch set json file.

JSON path based patches can be applied to one or more existing files by setting the variable PATCH_DEFINITIONS to the path of a directory that contains one or more patch definition json files or a patch set json file.

The file and value fields of the patch definitions may contain ${...} variable placeholders. The allowed environment variables in placeholders can be restricted by setting REPLACE_ENV_VARIABLE_PREFIX, which defaults to "CFG_".

The following example shows a patch-set file were various fields in the paper.yaml configuration file can be modified and added:

{
  "patches": [
    {
      "file": "/data/paper.yml",
      "ops": [
        {
          "$set": {
            "path": "$.verbose",
            "value": true
          }
        },
        {
          "$set": {
            "path": "$.settings['velocity-support'].enabled",
            "value": "${CFG_VELOCITY_ENABLED}",
            "value-type": "bool"
          }
        },
        {
          "$put": {
            "path": "$.settings",
            "key": "my-test-setting",
            "value": "testing"
          }
        }
      ]
    }
  ]
}

Supports the file formats:

Scenarios

Running non-root

This image may be run as a non-root user but does require an attached /server volume that is writable by that uid, such as:

docker run ... -u $uid -v $(pwd)/data:/server itzg/mc-proxy

Java Versions

The latest image tag is based on Java 21, but alternate image tags are available to run with a different java version.

The image Java variant can be used as shown here:

itzg/mc-proxy:{variant}

or using release version, such as 2024.5.0

itzg/mc-proxy:{release}-{variant}
Variant Java Version CPU types
latest 21 amd64,arm64
java21 21 amd64,arm64
java17 17 amd64,arm64,armv7
java11 11 amd64,arm64,armv7
java8 8 amd64,arm64,armv7