{"id":16540786,"url":"https://github.com/itzg/docker-mc-proxy","last_synced_at":"2025-05-16T09:05:48.518Z","repository":{"id":21449963,"uuid":"92781038","full_name":"itzg/docker-mc-proxy","owner":"itzg","description":"Docker image that provides a choice of Minecraft proxies, such as BungeeCord and Velocity","archived":false,"fork":false,"pushed_at":"2025-04-28T13:26:39.000Z","size":236,"stargazers_count":251,"open_issues_count":6,"forks_count":66,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-11T23:07:31.670Z","etag":null,"topics":["bungeecord","docker-image","minecraft-server","papermc"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itzg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-05-29T22:54:28.000Z","updated_at":"2025-05-11T08:17:13.000Z","dependencies_parsed_at":"2023-12-25T16:20:38.242Z","dependency_job_id":"c713b25e-c6d1-426d-a231-7266efafced2","html_url":"https://github.com/itzg/docker-mc-proxy","commit_stats":{"total_commits":186,"total_committers":35,"mean_commits":5.314285714285714,"dds":0.4731182795698925,"last_synced_commit":"697abf48c0d9fa9bb4c5ea50079fb89317f1d875"},"previous_names":["itzg/docker-mc-proxy"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itzg%2Fdocker-mc-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itzg%2Fdocker-mc-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itzg%2Fdocker-mc-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itzg%2Fdocker-mc-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itzg","download_url":"https://codeload.github.com/itzg/docker-mc-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501557,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bungeecord","docker-image","minecraft-server","papermc"],"created_at":"2024-10-11T18:53:18.705Z","updated_at":"2025-05-16T09:05:43.508Z","avatar_url":"https://github.com/itzg.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"This is a Docker image that provides a choice of Minecraft proxies, such as [BungeeCord](https://www.spigotmc.org/wiki/bungeecord/) and [Velocity](https://papermc.io/software/velocity). It is intended to be used in combination with [itzg/minecraft-server](https://hub.docker.com/r/itzg/minecraft-server/) containers.\n\n[![Build and Publish](https://github.com/itzg/docker-bungeecord/actions/workflows/build.yml/badge.svg)](https://github.com/itzg/docker-bungeecord/actions/workflows/build.yml)\n\n## Using with itzg/minecraft-server image\n\nWhen using with the server image [itzg/minecraft-server](https://hub.docker.com/r/itzg/minecraft-server/)\nyou can disable online mode, which is required by bungeecord, by setting `ONLINE_MODE=FALSE`, such as\n\n```bash\ndocker run ... -e ONLINE_MODE=FALSE itzg/minecraft-server\n```\n\nThe following is an example that can be started with `docker compose up -d`:\n\n```yaml\nservices:\n  mc:\n    image: itzg/minecraft-server\n    environment:\n      EULA: \"TRUE\"\n      ONLINE_MODE: \"FALSE\"\n    volumes:\n      - mc-data:/data\n  proxy:\n    image: itzg/mc-proxy\n    environment:\n      BUNGEE_JAR_REVISION: \"1\"\n      CFG_MOTD: Powered by Docker\n      REPLACE_ENV_VARIABLES: \"true\"\n    ports:\n      - \"25565:25577\"\n    volumes:\n      - ./config.yml:/config/config.yml\n      - proxy-data:/server\n\nvolumes:\n  mc-data:\n  proxy-data:\n```\n\n## Healthcheck\n\nThis image contains [mc-monitor](https://github.com/itzg/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`\n\n```\nCONTAINER ID    IMAGE    COMMAND                         CREATED           STATUS                     PORTS                       NAMES\nb418af073764    mc       \"/usr/bin/run-bungeecord.sh\"    43 seconds ago    Up 41 seconds (healthy)    0.0.0.0:25577-\u003e25577/tcp    mc\n```\n\nYou can also query the container's health in a script friendly way:\n\n```\n\u003e docker container inspect -f \"{{.State.Health.Status}}\" mc\nhealthy\n```\n\n## Environment Settings\n\n* **TYPE**=BUNGEECORD\n\n  The type of the server. When the type is set to `CUSTOM`, the environment setting `BUNGEE_JAR_URL` is required.\n\n  Possible values: \n  - [`BUNGEECORD`](https://www.spigotmc.org/wiki/bungeecord/)\n  - [`WATERFALL`](https://github.com/PaperMC/Waterfall)\n  - [`VELOCITY`](https://velocitypowered.com/)\n  - `CUSTOM`\n\n* **MEMORY**=512m\n\n  The Java memory heap size to specify to the JVM. Setting this to an empty string will let the JVM calculate the heap size from the container declared memory limit. Be sure to consider adding `-XX:MaxRAMPercentage=\u003cn\u003e` (with `\u003cn\u003e` replaced) to `JVM_XX_OPTS`, where the JVM default is 25%.\n\n* **ICON**\n\n  Setting this to an image URL will download and (if required) convert the icon to a 64x64 PNG, and place it in `/server/server-icon.png`.\n\n* **OVERRIDE_ICON**\n\n  Will override any pre-existing server-icon.png file in the /server directory if `ICON` is set.\n\n* **INIT_MEMORY**=${MEMORY}\n\n  Can be set to use a different initial heap size.\n\n* **MAX_MEMORY**=${MEMORY}\n\n  Can be set to use a different max heap size.\n\n* **JVM_OPTS** / **JVM_XX_OPTS**\n\n  Additional space-separated options to pass to the JVM, where `JVM_XX_OPTS` will be added to the java command-line before `JVM_OPTS`.\n\n* **NETWORKADDRESS_CACHE_TTL**=60\n\n  Number of seconds to cache the successful network address lookups. A lower value is helpful when Minecraft server containers are restarted and/or rescheduled and re-assigned a new container IP address.\n\n* **PLUGINS**\n\n  Used to download a comma seperated list of *.jar urls to the plugins folder.\n\n  ```\n  -e PLUGINS=https://www.example.com/plugin1.jar,https://www.example.com/plugin2.jar\n  ```\n\n* **PLUGINS_FILE**\n\n  An alternative to `PLUGINS`. This variable `PLUGINS_FILE` can be set with the container path or URL of a text file listing a mod/plugin URLs on each line. For example, the following\n\n  ```\n  -e PLUGINS_FILE=/extras/plugins.txt\n  ```\n  would load a file in the container at `/extras/plugins.txt`. The file might look like:\n\n  ```\n  https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/bungeecord\n  # This line will be ignored\n  https://download.luckperms.net/1567/bungee/loader/LuckPerms-Bungee-5.4.150.jar\n  ```\n\n  It works exactly the same as [Mod/Plugin URL Listing File for itzg/minecraft-server](https://docker-minecraft-server.readthedocs.io/en/latest/mods-and-plugins/#modsplugins-list).\n\n* **SPIGET_PLUGINS**\n\n  The `SPIGET_PLUGINS` variable can be set with a comma-separated list of SpigotMC resource IDs to automatically download [SpigotMC plugins](https://www.spigotmc.org/resources/) using [the spiget API](https://spiget.org/). Resources that are zip files will be expanded into the plugins directory and resources that are simply jar files will be moved there.\n  \n  \u003e NOTE: the variable is purposely spelled SPIG**E**T with an \"E\"\n  \n  The **resource ID** can be located from the numerical part of the URL after the shortname and a dot. For example, the ID is **313** from\n\n  ```\n  https://www.spigotmc.org/resources/bungeetablistplus.313/\n                                                       ===\n  ```\n\n* **MODRINTH_PROJECTS**\n\n  Comma or newline separated list of project slugs (short name) or IDs. The project ID is located in the \"Technical information\" section. The slug is the part of the page URL that follows `/mod/`:\n  ```\n    https://modrinth.com/mod/fabric-api\n                             ----------\n                              |\n                              +-- project slug\n  ```\n  Also, a specific version/type can be declared using colon symbol and version id/type after the project slug. The version id can be found in the 'Metadata' section. Valid version types are `release`, `beta`, `alpha`.\n\n  Dependency resolution can be adjusted by setting `MODRINTH_DOWNLOAD_DEPENDENCIES` to `none`, `optional`, or `required` (the default).\n\n  **NOTE** The variable `MINECRAFT_VERSION` must be set to the corresponding Minecraft version. \n\n* **ENABLE_RCON**\n\n  Enable the rcon server (uses a third-party plugin to work).\n  - [orblazer/bungee-rcon](https://github.com/orblazer/bungee-rcon) for `BUNGEECORD`, `WATERFALL`, and `CUSTOM`\n  - [TribuFuForks/VelocityRcon](https://github.com/TribufuForks/VelocityRcon) for `VELOCITY`\n\n* **RCON_PORT**\n\n  Define the port for rcon\n\n* **RCON_PASSWORD**\n\n  Define the password for rcon\n\n## Optional Environment Settings\n\n* **BUNGEE_JOB_ID**=lastStableBuild\n\n  The Jenkins job ID of the artifact to download and run and is used when deriving the default value of `BUNGEE_JAR_URL`\n\n* **BUNGEE_JAR_REVISION**\n\n  Defaults to the value of `${BUNGEE_JOB_ID}`, but can be set to an arbitrarily incremented value to force an upgrade of the downloaded BungeeCord jar file.\n\n* **BUNGEE_BASE_URL**\n\n  Default to:\n\n  * (type `BUNGEECORD`): \u003chttps://ci.md-5.net/job/BungeeCord\u003e\n  * (type `WATERFALL`): \u003chttps://papermc.io/ci/job/Waterfall/\u003e\n\n  Used to derive the default value of `BUNGEE_JAR_URL`\n\n* **BUNGEE_JAR_URL**\n\n  If set, can specify a custom, fully qualified URL  of the BungeeCord.jar; however, you won't be able reference the other environment variables from within a `docker run` a compose file. Defaults to:\n\n  * (type: `BUNGEECORD`): `${BUNGEE_BASE_URL}/${BUNGEE_JOB_ID}/artifact/bootstrap/target/BungeeCord.jar`\n  \n  This takes precedence over `BUNGEE_JAR_FILE`.\n\n* **BUNGEE_JAR_FILE**\n\n  For `TYPE=CUSTOM`, allows setting a custom BungeeCord JAR that is located inside the container.\n  \n  Must be a valid path of an existing file.\n\n* **WATERFALL_VERSION**=latest\n\n  For `TYPE=WATERFALL`, allows downloading a specific release stream of Waterfall.\n\n* **WATERFALL_BUILD_ID**=latest\n\n  For `TYPE=WATERFALL`, allows downloading a specific build of Waterfall within the given version.\n\n* **VELOCITY_VERSION**=latest\n\n  For `TYPE=VELOCITY`, specifies the version of Velocity to download and run.\n\n* **VELOCITY_BUILD_ID**=latest\n\n  For `TYPE=VELOCITY`, allows downloading a specific build of Velocity within the given version.\n\n* **HEALTH_HOST**=localhost\n\n  Allows for configuring the host contacted for container health check.\n\n* **HEALTH_USE_PROXY**=false\n\n  Set to \"true\" when using Bungeecord's `proxy_protocol` option\n\n* **ENABLE_JMX**=false\n\n  To enable remote JMX, such as for profiling with VisualVM or JMC, add the environment variable `ENABLE_JMX=true`, set `JMX_HOST` to the IP/host running the Docker container, and add a port forwarding of TCP port 7091\n\n## Volumes\n\n* **/server**\n\n  The working directory where BungeeCord is started. This is the directory\n  where its `config.yml` will be loaded.\n\n* **/plugins**\n\n  Plugins will be copied across from this directory before the server is started.\n\n* **/config**\n\n  The contents of this directory will be synchronized into the `/server` directory. Variable placeholders within the files will be processed as described [in the section below](#replacing-variables-inside-configs) unless `REPLACE_ENV_DURING_SYNC` is set to \"false\".\n\n## Ports\n\n* **25577**\n\n  The default listening port of BungeeCord and Waterfall, which you will typically want to port map\n  to the standard Minecraft server port of 25565 using:\n\n  ```\n  -p 25565:25577\n  ```\n\n* **25565**\n\n  The default listening port of Velocity; however, [the example](docs/velocity/docker-compose.yml) shows that can be altered by setting `bind` in `velocity.toml` to \"localhost:25577\" to match BungeeCord/Waterfall.\n\nThe health check will try to determine the correct port to check based upon the type and configuration; however, you can always set the environment variable `SERVER_PORT` to force a specific port to evaluate.\n\n## Java Versions\n\nThe following table shows the Java versions and CPU architectures supported by the image tags:\n\n| Tag    | Java | Architectures       |\n|--------|------|---------------------|\n| latest | 17   | amd64, arm64, armv7 |\n| java8  | 8    | amd64, arm64, armv7 |\n| java11 | 11   | amd64, arm64, armv7 |\n\n## Interacting with the server\n\n[RCON](http://wiki.vg/RCON) is enabled by default, so you can `exec` into the container to\naccess the Bungeecord server console:\n\n```\ndocker exec -i mc rcon-cli\n```\n\nNote: The `-i` is required for interactive use of rcon-cli.\n\nTo run a simple, one-shot command, such as stopping a Bungeecord server, pass the command as\narguments to `rcon-cli`, such as:\n\n```\ndocker exec mc rcon-cli en\n```\n\n_The `-i` is not needed in this case._\n\nIn order to attach and interact with the Bungeecord server, add `-it` when starting the container, such as\n\n    docker run -d -it -p 25565:25577 --name mc itzg/mc-proxy\n\nWith that you can attach and interact at any time using\n\n    docker attach mc\n\nand then Control-p Control-q to **detach**.\n\nFor remote access, configure your Docker daemon to use a `tcp` socket (such as `-H tcp://0.0.0.0:2375`)\nand attach from another machine:\n\n    docker -H $HOST:2375 attach mc\n\nUnless you're on a home/private LAN, you should [enable TLS access](https://docs.docker.com/articles/https/).\n\n## BungeeCord Configuration\n\n[BungeeCord Configuration Guide](https://www.spigotmc.org/wiki/bungeecord-configuration-guide/)\n\n### Generic pack files\n\nTo 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.\n\nIf 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.\n\nTo 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\n\n```\nGENERIC_PACKS=configs-v9.0.1,mods-v4.3.6\nGENERIC_PACKS_PREFIX=https://cdn.example.org/\nGENERIC_PACKS_SUFFIX=.zip\n```\n\nwould expand to `https://cdn.example.org/configs-v9.0.1.zip,https://cdn.example.org/mods-v4.3.6.zip`.\n\n### Replacing variables inside configs\n\nSometimes you have mods or plugins that require configuration information that is only available at runtime.\nFor example if you need to configure a plugin to connect to a database,\nyou don't want to include this information in your Git repository or Docker image.\nOr maybe you have some runtime information like the server name that needs to be set\nin your config files after the container starts.\n\nFor those cases there is the option to replace defined variables inside your configs\nwith environment variables defined at container runtime.\n\nIf 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.\n\nWith `REPLACE_ENV_VARIABLE_PREFIX` you can define a prefix, where the default is `CFG_`, to only match predefined environment variables.\n\nIf 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.\n\nHere is a full example where we want to replace values inside a `database.yml`.\n\n```yml\n\n---\ndatabase:\n  host: ${CFG_DB_HOST}\n  name: ${CFG_DB_NAME}\n  password: ${CFG_DB_PASSWORD}\n```\n\nThis is how your `docker-compose.yml` file could look like:\n\n```yml\nversion: \"3.8\"\n# Other docker-compose examples in /examples\n\nservices:\n  proxy:\n    image: itzg/mc-proxy\n    ports:\n      - \"25577:25577\"\n    volumes:\n      - \"proxy:/server\"\n    environment:\n      # enable env variable replacement\n      REPLACE_ENV_VARIABLES: \"TRUE\"\n      # define an optional prefix for your env variables you want to replace\n      ENV_VARIABLE_PREFIX: \"CFG_\"\n      # and here are the actual variables\n      CFG_DB_HOST: \"http://localhost:3306\"\n      CFG_DB_NAME: \"minecraft\"\n      CFG_DB_PASSWORD_FILE: \"/run/secrets/db_password\"\n    restart: always\n\nvolumes:\n  proxy:\n\nsecrets:\n  db_password:\n    file: ./db_password\n```\n\nThe content of `db_password`:\n\n    ug23u3bg39o-ogADSs\n\n### Patching existing files\n\nJSON 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](https://github.com/itzg/mc-image-helper#patchdefinition) or a [patch set json file](https://github.com/itzg/mc-image-helper#patchset).\n\nThe `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_\".\n\nThe following example shows a patch-set file were various fields in the `paper.yaml` configuration file can be modified and added:\n\n```json\n{\n  \"patches\": [\n    {\n      \"file\": \"/data/paper.yml\",\n      \"ops\": [\n        {\n          \"$set\": {\n            \"path\": \"$.verbose\",\n            \"value\": true\n          }\n        },\n        {\n          \"$set\": {\n            \"path\": \"$.settings['velocity-support'].enabled\",\n            \"value\": \"${CFG_VELOCITY_ENABLED}\",\n            \"value-type\": \"bool\"\n          }\n        },\n        {\n          \"$put\": {\n            \"path\": \"$.settings\",\n            \"key\": \"my-test-setting\",\n            \"value\": \"testing\"\n          }\n        }\n      ]\n    }\n  ]\n}\n```\n\nSupports the file formats:\n- JSON\n- JSON5\n- Yaml\n- TOML, but processed output is not pretty\n\n## Scenarios\n\n### Running non-root\n\nThis image may be run as a non-root user but does require an attached `/server`\nvolume that is writable by that uid, such as:\n\n    docker run ... -u $uid -v $(pwd)/data:/server itzg/mc-proxy\n\n## Java Versions\n\nThe `latest` image tag is based on Java 21, but alternate image tags are available to run with a different java version. \n\nThe image Java variant can be used as shown here:\n\n    itzg/mc-proxy:{variant}\n\nor using release version, such as `2024.5.0`\n\n    itzg/mc-proxy:{release}-{variant}\n\n| Variant | Java Version | CPU types         |\n|---------|--------------|-------------------|\n| latest  | 21           | amd64,arm64       |\n| java21  | 21           | amd64,arm64       |\n| java17  | 17           | amd64,arm64,armv7 |\n| java11  | 11           | amd64,arm64,armv7 |\n| java8   | 8            | amd64,arm64,armv7 |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitzg%2Fdocker-mc-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitzg%2Fdocker-mc-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitzg%2Fdocker-mc-proxy/lists"}