Docker

VoxelDash One ships as a ready-to-run container image on the GitHub Container Registry. The image bundles the backend together with the web dashboard, so a single docker run gives you the full thing, no separate UI to build.

The image is published at:

ghcr.io/gnmyt/voxeldash-one

Quick start

Pull the image and run it with host networking, giving it a place to keep its data:

docker run -d \
  --name voxeldash-one \
  --network host \
  -v voxeldash-one-data:/data \
  ghcr.io/gnmyt/voxeldash-one:latest

Open http://localhost:7867, create your admin account, and you are ready to create your first server.

Image tags

The registry carries one tag per release channel, plus version-pinned tags, so you can track exactly as closely as you like.

For production, pin a stable version (ghcr.io/gnmyt/voxeldash-one:1.2.0) or follow latest. Use beta to try upcoming features, and dev only if you want the very latest commit.

Using Docker Compose

A compose.yaml keeps the networking, volume, and restart policy in one place:

services:
  voxeldash-one:
    image: ghcr.io/gnmyt/voxeldash-one:latest
    container_name: voxeldash-one
    restart: unless-stopped
    network_mode: host
    volumes:
      - voxeldash-one-data:/data

volumes:
  voxeldash-one-data:

Then:

docker compose up -d

Configuration

The image reads the same environment variables as the binary, with container-friendly defaults already set (VOXELDASH_HOME=/data). You normally only touch PORT if 7867 clashes with something else, and you should leave VOXELDASH_HOME and VOXELDASH_UI at their defaults.

Pass them with -e, for example to move the dashboard to port 8080:

docker run -d \
  --name voxeldash-one \
  --network host \
  -e PORT=8080 \
  -v voxeldash-one-data:/data \
  ghcr.io/gnmyt/voxeldash-one:latest

With host networking the dashboard simply listens on whatever PORT you set, no separate mapping to keep in sync.

How networking works

The managed Minecraft servers run as child processes inside the container and bind to loopback, then reverse-tunnel their console and control traffic back to One. With host networking the container's loopback is the host's, so the servers sit directly on the host network and One's dashboard is reachable on 7867, all without exposing a port per server.

To let players reach a server from the internet, use the built-in playit.gg forwarding: it gives each server a public address with nothing to configure on the host.

Without host networking

On Docker Desktop (macOS/Windows), host networking is not fully supported, so publish the dashboard port instead:

docker run -d \
  --name voxeldash-one \
  -p 7867:7867 \
  -v voxeldash-one-data:/data \
  ghcr.io/gnmyt/voxeldash-one:latest

Leave MASTER_HOST at its default. The managed servers run as child processes inside this same container and dial One over loopback, so the reverse tunnel works regardless of networking mode. What bridge mode cannot do is expose the game servers themselves: they bind to loopback inside the container, which Docker's -p publishing (it targets the bridge interface, not loopback) cannot reach. Use playit.gg forwarding to give players a way in, it dials out from inside the container and works in any mode.

Persisting and backing up data

The whole state of your instance is the /data volume. To back it up, stop the container and copy the volume, or use a bind mount instead of a named volume so the files sit in a folder you control:

docker run -d \
  --name voxeldash-one \
  --network host \
  -v /srv/voxeldash-one:/data \
  ghcr.io/gnmyt/voxeldash-one:latest

Back up /srv/voxeldash-one and you have backed up your account, your servers, and their worlds.

Updating

The in-app self-updater is disabled in the container, updates are done by pulling a newer image, which is the normal Docker workflow. Because all your state lives in the /data volume, recreating the container keeps everything.

docker pull ghcr.io/gnmyt/voxeldash-one:latest
docker rm -f voxeldash-one
docker run -d \
  --name voxeldash-one \
  --network host \
  -v voxeldash-one-data:/data \
  ghcr.io/gnmyt/voxeldash-one:latest

With Compose it is simply:

docker compose pull
docker compose up -d

Putting it behind a reverse proxy

One listens on a single port and uses WebSockets for the live console and the reverse tunnel. The same setup as the binary applies, see the Reverse Proxy guide and point it at the published container port (7867 by default).