Docker

This guide covers running Encore Server as a Docker container on Ubuntu 24.04.

Build the image

From the repo root:

docker build -t encore-server ./server

To customize the game port range documented in the image metadata, use the GAME_PORT_RANGE build arg (default: 7000-7099):

docker build --build-arg GAME_PORT_RANGE=5000-5999 -t encore-server ./server

This only affects EXPOSE metadata. The ports you actually publish at runtime must match ENCORE_PORT_POOLS.

Environment variables

Configuration is generated from environment variables at container startup. A config file is written to /etc/encore/config.toml before the server starts.

Variable	Required	Default	Description
ENCORE_ID	yes	—	Server identifier (encore_XXXXXXXXXX) — generate with encore install
ENCORE_ADMIN_TOKEN	yes	—	Admin API authentication token
ENCORE_PORT_POOLS	no	—	Comma-separated port ranges, e.g. 7000-7099,7100-7199
ENCORE_PUBLIC_HOST	no	127.0.0.1	Public hostname or IP returned to game clients
ENCORE_BIND	no	0.0.0.0:8080	HTTP listen address
ENCORE_UPLOAD_FOLDER	no	/var/lib/encore/uploads	Directory for uploaded game server binaries
ENCORE_MAX_UPLOAD_SIZE	no	524288000 (500 MiB)	Maximum upload size in bytes

Running the container

docker run -d \
  --name encore \
  -e ENCORE_ID=encore_AbCdEfGhIj \
  -e ENCORE_ADMIN_TOKEN=your-secret-token \
  -e ENCORE_PORT_POOLS="7000-7099" \
  -e ENCORE_PUBLIC_HOST=game.example.com \
  -p 8080:8080 \
  -p 7000-7099:7000-7099/udp \
  -v /opt/gameservers:/opt/gameservers:ro \
  -v /etc/encore/templates:/etc/encore/templates \
  -v /var/lib/encore/uploads:/var/lib/encore/uploads \
  encore-server

The game server binaries and template files live on the host. Mount them into the container so paths declared in your templates resolve correctly.

If you use the binary upload API (POST /api/v1/uploads), the uploads and templates volumes must be writable. Uploaded binaries are stored in the upload folder and template CRUD writes .toml files to the template folder.

Docker Compose

services:
  encore:
    image: encore-server
    build:
      context: ./server
      args:
        GAME_PORT_RANGE: "7000-7099"
    environment:
      ENCORE_ID: encore_AbCdEfGhIj
      ENCORE_ADMIN_TOKEN: your-secret-token
      ENCORE_PORT_POOLS: "7000-7099"
      ENCORE_PUBLIC_HOST: game.example.com
    ports:
      - "8080:8080"
      - "7000-7099:7000-7099/udp"
    volumes:
      - /opt/gameservers:/opt/gameservers:ro
      - /etc/encore/templates:/etc/encore/templates
      - /var/lib/encore/uploads:/var/lib/encore/uploads
    restart: unless-stopped

cgroup v2 isolation

If your templates use [template.isolation.cgroup], the container needs the SYS_ADMIN capability to create and manage cgroup v2 subgroups:

docker run --cap-add SYS_ADMIN ...

Or in Compose:

    cap_add:
      - SYS_ADMIN

Without this capability, instances that require cgroup isolation will fail to spawn. Templates without isolation are unaffected.

Validate and smoke-check

Once the container is running:

# Health check
curl http://localhost:8080/health

# List templates (requires admin token)
curl -H "X-Admin-Token: your-secret-token" \
  http://localhost:8080/api/v1/templates

Common pitfalls

• ENCORE_PUBLIC_HOST must be set to a host reachable by game clients — the default 127.0.0.1 is only useful for local testing.
• The UDP port range in -p must match ENCORE_PORT_POOLS exactly. Mismatches result in unreachable game server ports.
• Game binary paths in template files must resolve inside the container. Use the same absolute path for both the volume mount target and the binary_path in your template.