Cubeherd

Install Cubeherd

Cubeherd runs on the same host as your Minecraft servers. You need Docker with the Compose plugin.

With Docker Compose (recommended)

sudo mkdir -p /srv/cubeherd

Save this as compose.yml and start it with docker compose up -d:

services:
  cubeherd:
    image: ghcr.io/matserix/cubeherd:latest
    container_name: cubeherd
    restart: unless-stopped
    ports:
      - "8420:8420"          # only expose on the LAN/VPN
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /srv/cubeherd:/srv/cubeherd
    environment:
      CUBEHERD_DATA: /srv/cubeherd
      TZ: Europe/Berlin       # for backup schedules

Then open http://<host>:8420 and set the admin password on first visit.

The data directory must have the same path inside the container as on the host (/srv/cubeherd:/srv/cubeherd), because Docker resolves the Minecraft servers' bind mounts on the host.

As a binary

Build it with Go, or grab a build from the releases page:

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o cubeherd ./cmd/cubeherd
sudo CUBEHERD_DATA=/srv/cubeherd ./cubeherd

Configuration

VariableDefaultMeaning
CUBEHERD_DATA/srv/cubeherd as root, otherwise ./cubeherd-dataData directory
CUBEHERD_LISTEN:8420Web server address
DOCKER_HOST/var/run/docker.sock, falling back to ~/.docker/run/docker.sockDocker socket
TZUTCDefault time zone, unless one is chosen in the settings

Where your data lives

There is no database. Each server gets a folder in the data directory with a cubeherd.json definition, a generated compose.yml and its data/ directory with world, configs and mods. Servers keep working with docker compose without Cubeherd. Existing itzg containers can be adopted.

Security

Anyone who can operate Cubeherd controls Docker and therefore, in practice, the entire host. Only expose it on your LAN or via VPN, never directly to the internet. It has a single admin account (bcrypt), signed session cookies (SameSite=Strict), login throttling and CSRF protection.

View on GitHubRead the architecture