Install with Docker

What you need

• A Linux machine (x86-64 or ARM64) with Docker Engine. A VM, a Proxmox container with Docker, or a spare PC all work.
• Memory for your servers: about 2 GB per small Vanilla or Paper server, 6 GB or more for large modpacks. NetherNode itself uses very little.
• Port 25565 (TCP) reachable from the internet, if people outside your network will play. See DNS and ports.

Start it

One command:

docker run -d --name nethernode --restart unless-stopped --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v nethernode-data:/data \
  ghcr.io/ziggy46/nethernode:latest

Or with Docker Compose, using docker-compose.yml from the NetherNode repository:

docker compose up -d
docker compose logs -f   # optional: watch it start

Open http://<machine>:8080 and create the owner account. The first server takes a minute or two: Docker downloads the Minecraft server image, then the server downloads its own files.

Image tags

Tag	What it is
latest	The newest release
0.2.9, 0.2	A release, or the newest patch of a minor version
edge	The newest edge build: new features before they’re released
0.2.10-edge.41	One edge build
sha-1a2b3c4	The edge build of one commit

Rather than changing the tag, pick the update channel in Settings › Notifications › New versions; the panel then updates itself to the newest release or edge build (update channels).

Settings

The defaults suit most setups: the panel on port 8080, players on port 25565, and servers’ own ports from 30000 to 30999 on 127.0.0.1. Every configuration setting can be set with an environment variable, either -e with docker run or under environment: in the compose file. Some useful ones:

Variable	Meaning
NETHERNODE_HTTP__BIND	The panel’s address (default 0.0.0.0:8080)
NETHERNODE_PROXY__DEFAULT_LISTENER	Where players connect (default 0.0.0.0:25565; first run only, then edit listeners in the panel)
NETHERNODE_HTTP__TRUST_PROXY_HEADERS	true behind a reverse proxy or tunnel

The nethernode-data volume holds worlds, backups and settings. A host folder works too: -v /srv/nethernode:/data. Server files in it are owned by user 1000, the Minecraft image’s own user.

How the data folder works

NetherNode mounts each server’s folder into that server’s container. Docker needs the folder’s path on the host for that, which differs from /data inside NetherNode’s container. NetherNode works it out by inspecting its own container, so the data folder can be any host directory or named volume. If it can’t (for example when the Docker socket is behind a filtering proxy), the log says so, and you can set it yourself:

environment:
  NETHERNODE_DOCKER__HOST_DATA_DIR: /srv/nethernode/data

Host or bridge networking

The command and the compose file both use host networking: the panel and the proxy listen directly on the machine’s addresses, and servers’ ports stay on 127.0.0.1 where only NetherNode can reach them. That’s the simplest setup.

Where host networking isn’t available (Docker Desktop), use bridge networking: drop --network host (or network_mode: host), publish the ports, and tell NetherNode to reach its servers through the Docker bridge gateway. In the compose file:

ports:
  - "8080:8080"
  - "25565:25565"
environment:
  NETHERNODE_DOCKER__BACKEND_IP: "172.17.0.1"   # docker network inspect bridge

In bridge mode NetherNode sees every player as coming from the gateway address, so per-IP bans and limits apply to everyone at once. Prefer host networking where you can.

Updating

With Docker Compose:

docker compose pull
docker compose up -d

The repository’s docker-compose.yml sets pull_policy: always, so docker compose up -d alone also fetches a newer image. If you wrote your own compose file around :latest, add that line or always pull first: otherwise Docker keeps starting the copy of :latest it downloaded first.

Nodes on other machines update themselves to the panel’s version once it’s running.

With docker run, pull the new image, remove the container, and run the same command again; the data volume stays:

docker pull ghcr.io/ziggy46/nethernode:latest
docker rm -f nethernode

Servers keep running while NetherNode restarts; it reconnects to them. Back up the data folder before major updates.