Server setup · Chunk Survival

Requirements

A 64-bit host with Docker Engine and the Docker Compose plugin.
TCP port 25599 open through the host firewall and router.
A copy of docker-compose-server.yml and the repository's config directory.
Enough memory for every enabled backend. Remove game-mode services you do not plan to host.

Install and start

Create a deployment directory, copy the Compose file and config directory into it, then create a .env file:

GHCR_OWNER=stoxello
TAG=latest
REQUIRE_AUTHORIZATION=false

Pull and start the cluster from that directory:

docker compose -f docker-compose-server.yml pull
docker compose -f docker-compose-server.yml up -d
docker compose -f docker-compose-server.yml ps

Players connect to the gateway at your-hostname:25599. Backend ports stay on the private Compose network.

Configure the cluster

Each file under config/ describes one backend. The gateway routes players to those services. Edit the supplied files before starting the cluster, and restart the affected service after a change.

Setting	Purpose
`role`	Selects hub, survival, or minigame behavior.
`minigame`	Selects the plugin-backed game mode for a minigame backend.
`chunkclaims`	Enables territory claims on survival backends.
`dayLengthSeconds`	Controls the full in-game day and night cycle.

For a listed public server, register it through the Player ID service and set:

REQUIRE_AUTHORIZATION=true
AUTHORIZATION_URL=https://id.chunksurvival.com
SERVER_ID=your-server-id
SERVER_KEY=your-server-key

Keep SERVER_KEY private. Store it in your deployment environment or an untracked .env file.

Operate and update

# Follow logs
docker compose -f docker-compose-server.yml logs -f gateway survival

# Restart one backend
docker compose -f docker-compose-server.yml restart survival

# Pull a new release and recreate services
docker compose -f docker-compose-server.yml pull
docker compose -f docker-compose-server.yml up -d --remove-orphans

Pin TAG to a known release when predictable upgrades matter. Review logs after every update before sending players back to the server.

Install and update plugins

Plugins run inside the authoritative server process. Only install code you trust. Give every modern plugin its own directory:

Plugins/
└── HelloPlugin/
    ├── plugin.yml
    ├── HelloPlugin.dll
    └── dependency.dll

Stop the backend that will load the plugin.
Extract the plugin directory beneath the backend's Plugins directory.
Do not include BlockGame.PluginApi.dll; the server supplies it.
Start the backend and look for [plugins] Enabled Name vVersion in its logs.

Set PLUGINS_PATH to use another plugin root. In Docker, mount that root at /data/Plugins. A plugin's writable files live under its own data directory.

Runtime reload is intentionally unsupported. Restart after installing or updating a plugin so callbacks, tasks, dependencies, and static state begin cleanly.

Persistent data and backups

The supplied Compose deployment keeps survival worlds in named volumes. Plugin configuration and metadata must also be stored on a persistent mount. Back up volumes while the affected backend is stopped, or use a storage snapshot that guarantees a consistent point in time.

Test restoration regularly. A backup is only useful when it can recreate both the world and the plugin data that describes it.

Security checklist

Expose only gateway TCP port 25599; do not publish backend ports.
Use server authorization for public deployments and rotate a leaked key immediately.
Run current container images and pin versions when you need a controlled rollout.
Review plugin source and dependencies. Plugins inherit the server process's operating-system permissions.
Keep world, credentials, and plugin data out of the container image and in protected persistent storage.

Develop a plugin Check official servers

Run a Chunk Survival server