Running Gate in Docker

Gate ships in packaged Docker images that you can use to run Gate containers or base your own images on. You can also run it in Kubernetes.

Version Tags

You can use specific version tags instead of the latest. Every commit to the main branch is built and pushed to the latest tag as well as the commit's short SHA like 6d3671c.

Image Variants

Gate provides two Docker image variants:

Standard Image (ghcr.io/minekube/gate:latest)

The standard Gate image is based on a minimal distroless base image. This is the recommended image for most use cases as it has a smaller footprint and enhanced security.

JRE Variant (ghcr.io/minekube/gate/jre:latest)

The JRE variant includes Java Runtime Environment (JRE) and is required for Bedrock Edition support. This image is based on eclipse-temurin:25-jre-alpine and includes Java necessary to run Geyser for Bedrock cross-play.

When to Use the JRE Variant

Use ghcr.io/minekube/gate/jre:latest if you:

• Need Bedrock Edition support (cross-play with mobile, console, and Windows Bedrock players)
• Are using Gate's managed Geyser mode
• Require Java runtime in your container

For all other use cases, use the standard ghcr.io/minekube/gate:latest image.

docker run

docker run -it --rm ghcr.io/minekube/gate:latest

This command will pull and run the latest Gate image.

• -it - Run interactively and allocate a pseudo-TTY.
  • Alternatively using -d would run in detached mode.
• --rm - Removes the container after it exits.

Mounting a config file

A complete config is located in repo config.yml.

Standard Image

docker run -it --rm \
  -v PATH-TO-CONFIG/config.yml:/config.yml \
  ghcr.io/minekube/gate:latest

JRE Variant (Bedrock Support)

docker run -it --rm \
  -v PATH-TO-CONFIG/config.yml:/config.yml \
  ghcr.io/minekube/gate/jre:latest

This command will pull and run the latest Gate image.

• -v PATH-TO-CONFIG/config.yml:/config.yml - Mounts the config file from the host system into the container.
• Use the JRE variant if you need Bedrock Edition support.

Mounting a config file and Minekube Connect token

Using an environment variable for the token

Standard Image

docker run -it --rm \
  -v PATH-TO-CONFIG/config.yml:/config.yml \
  -e CONNECT_TOKEN=YOUR-TOKEN \
  ghcr.io/minekube/gate:latest

JRE Variant (Bedrock Support)

docker run -it --rm \
  -v PATH-TO-CONFIG/config.yml:/config.yml \
  -e CONNECT_TOKEN=YOUR-TOKEN \
  ghcr.io/minekube/gate/jre:latest

Note: The CONNECT_TOKEN environment variable takes precedence over the connect.json file, so if both are provided, the token from the environment variable will be used instead.

Using a volume for the token

Standard Image

docker run -it --rm \
  -v PATH-TO-CONFIG/config.yml:/config.yml \
  -v PATH-TO-CONFIG/connect.json:/connect.json \
  ghcr.io/minekube/gate:latest

JRE Variant (Bedrock Support)

docker run -it --rm \
  -v PATH-TO-CONFIG/config.yml:/config.yml \
  -v PATH-TO-CONFIG/connect.json:/connect.json \
  ghcr.io/minekube/gate/jre:latest

A Minekube Connect token json file can be automatically generated by running Gate with connect.enable: true in the config.

{ "token": "YOUR-TOKEN" }

docker-compose.yaml

Copy the following snippet into a docker-compose.yaml file and run docker-compose up.

version: '3.9'

services:
  gate:
    image: ghcr.io/minekube/gate:latest
    container_name: gate
    restart: unless-stopped
    network_mode: host
    volumes:
      - PATH-TO-CONFIG/config.yml:/config.yml
    #- PATH-TO-TOKEN/connect.json:/connect.json

Running docker-compose down will stop and remove the containers.

We provide an example that configures Gate with two Minecraft servers.

git clone https://github.com/minekube/gate.git
cd gate/.examples/docker-compose
docker-compose up

The files of the two servers are located in the serverdata* directories. You can join at localhost:25565 and use /server to switch between the servers.

Using the JRE Variant for Bedrock Support

If you need Bedrock Edition support, use the JRE variant image:

version: '3.9'

services:
  gate:
    image: ghcr.io/minekube/gate/jre:latest
    container_name: gate
    restart: unless-stopped
    network_mode: host
    volumes:
      - PATH-TO-CONFIG/config.yml:/config.yml

The JRE variant includes Java Runtime Environment required for Geyser to run. See the Bedrock Edition guide for complete Bedrock setup instructions.

Troubleshooting

If you see the following error:

Unable to find image 'ghcr.io/minekube/gate:latest' locally
docker: Error response from daemon: Head "https://ghcr.io/v2/minekube/gate/manifests/latest": denied: denied.
See 'docker run --help'.

do

docker logout ghcr.io

It may be because you are logged in to the GitHub Container Registry with an outdated personal access token (PAT). Simply logout or login with a new token. It's worse to provide a bad token than not to provide a token at all. GitHub sets tokens to expire after 30 days by default.