Add a Node

Any Linux machine with Docker can be a Node. Its Agent connects out to the Controller, so the machine needs no open ports except the Minecraft ports players use.

1. In the web UI, open Nodes and choose Add Node. Give it a name, such as node-2.

2. Shardkeep shows a one-time enrollment token and the command to start the Agent. The token works once and expires within the hour, so run it soon. Treat it like a password.

3. On the new machine, run the command it shows. It looks like this:

   docker run -d --name shardkeep-agent --restart unless-stopped \
     -e SHARDKEEP_ENROLL_TOKEN='…' \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v shardkeep-agent:/var/lib/shardkeep-agent \
     -v /proc:/host/proc:ro \
     registry.gitlab.com/shardkeep/shardkeep/agent:1.20.0 -controller shardkeep.example.com:8443

   A Docker Compose version is shown too.

4. The Node shows as Healthy once its Agent has enrolled and connected.

What happens when it enrolls

The Agent generates its own private key, which never leaves the machine, and sends the Controller a certificate request with the token. The Controller’s certificate authority signs it, and from then on the Agent connects with mutual TLS on port 8443. The token is no longer needed; it is safe to leave it out of later runs.

The shardkeep-agent volume holds the Agent’s identity and its copy of what should run. Keep it: without it, the machine has to enroll again as a new Node.

The Node’s address

When the proxy runs on another Node, it reaches this Node’s servers at the address this Agent connects from. If that is not the address other Nodes can use (NAT, several network interfaces), set it on the Node’s page.

Removing a Node

Disable a Node to stop new servers being placed on it. Revoke it to cut it off for good: its Agent stops every server it runs and does nothing more, even after restarts. To reuse the machine, enroll it again as a new Node.