itzg / mc-router

Routes Minecraft Java Edition client connections to backend servers based upon the requested server address. This is quite helpful for home network deployments where any number of Minecraft servers can be multiplexed onto a single, public IP address and standard Minecraft port. It works great with itzg/minecraft-server, but can be used with any Minecraft server. Stand-alone binaries are also published for Linux, Mac, and Windows if not wanting to use containers at all. Some other features included: • Dynamic auto-discovery of backend servers in Kubernetes and Docker which allows for "zero-config" mapping of your Minecraft server hostnames to backend servers protected behind mc-router. • Minimizes unwanted intrusions by disallowing Minecraft port scanners that are not specifying a mapped server hostname. • Rate limits incoming connections to reduce DDoS attacks. • Can be configured to allow/deny IP addresses or ranges • Includes a webhook integration for notifying other systems when a player connects and disconnects from a server. • Can auto-scale (between zero and one) backend servers deployed as Kubernetes StatefulSets • or start and stop backend servers running as docker containers. • Built-in ngrok integration where mc-router acts as an agent • Exports/exposes metrics for various Prometheus and InfluxDB. If enabled, includes player login metrics. Usage Docker Multi-Architecture Image The multi-architecture image published at Docker Hub supports amd64, arm64, and arm32v6 (i.e. RaspberryPi). Docker Compose Usage The diagram below shows how this configures two Minecraft server services named and , which also become the internal network aliases. _Notice those services don't need their ports exposed since the internal networking allows for the inter-container access._ The service is only one of the services that needs to exposed on the external network. The declares how the hostname users will enter into their Minecraft client will map to the internal services. To test out this example, add these two entries to my "hosts" file: Using Docker auto-discovery When running in a Docker environment you can pass the or command-line argument or set the environment variables or to "true". With that, it will poll the Docker API periodically to find all the running containers/services for Minecraft instances. To enable discovery, you have to set the label on the container. When using in Docker, make sure to volume mount the Docker socket into the container, such as These are the labels scanned: • : Used to configure the hostname the Minecraft clients would use to connect to the server. The container/service endpoint will be used as the routed backend. You can use more than one hostname by splitting it with a comma or newline. Whitespace around commas is automatically trimmed. For example: , , or . • : This value must be set to the port the Minecraft server is listening on. The default value is 25565. • : Set this to a truthy value to make this server the default backend. Please note that is still required to be set. • : Specify the network you are using for the router if multiple are present in the container/service. You can either use the network ID, it's full name or an alias. • : Per-container override to enable/disable auto scale up for Docker. When true (or left unspecified and the global flag is enabled), mc-router will start or unpause this container when a client connects to the declared hostname(s). • : Per-container override to enable/disable auto scale down for Docker. When true (or left unspecified and the global flag is enabled), mc-router will stop this container after it has been idle for the configured duration. • : Per-container override for MOTD to show when container is scaled to zero. If empty or not set the host will appear unresponsive. • : Per-container override for MOTD to show while the container is waking and not yet reachable. If empty or not set, the global value is used. Docker Auto Scale Up/Down To use scale-to-zero with Docker containers: • Start mc-router with Docker discovery and scaling enabled, for example: • Label each Minecraft container with at least . You can also set per-container autoscale overrides using and labels. For usage with docker compose refer to the examples/docker-autoscale/compose.yml or examples/docker-autoscale/compose-minimal.yml examples. Behavior: • When a client connects to a labeled hostname and the container is stopped or paused, mc-router will start/unpause it and wait until it becomes reachable (up to ~60s). • While that wake-up is in progress and status pings are received, mc-router can return a loading MOTD (per-container override or ). • When no clients remain connected and the idle timer elapses ( ), mc-router gracefully stops the container. Note: Docker Swarm discovery is supported; however, auto scale up/down is not yet supported for Swarm services. Example Docker deployment Refer to this example docker-compose.yml to see how to configure two different Minecraft servers and a instance for use with Docker service discovery. Example Docker Swarm deployment Refer to this example docker-compose.yml to see how to configure two different Minecraft servers and a instance for use with Docker Swarm service discovery. Routing Configuration The routing configuration allows routing via a config file rather than a command. You need to set or env variable. The following shows a JSON file for routes config, where can also be or omitted: Sending a SIGHUP signal will cause mc-router to reload the routes config from disk. The file can also be watched for changes by setting or the env variable to "true". Auto Scale Allow/Deny List The allow/deny list configuration allows limiting which players can scale up servers when using the option ( env variable) and which players can cancel an active down scaler when using the option ( env variable). Global allow/deny lists can be configured that apply to all backend servers, but server-…