From 3810764a10ec62a5aa53093eeab84715c10065bc Mon Sep 17 00:00:00 2001 From: Joshua Gilman Date: Fri, 20 Nov 2026 20:07:17 -0800 Subject: [PATCH] docs(calagopus): open servers to internet players with playit.gg --- docs/docs/runbooks/calagopus.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/docs/runbooks/calagopus.md b/docs/docs/runbooks/calagopus.md index aa8323e..3515e81 100644 --- a/docs/docs/runbooks/calagopus.md +++ b/docs/docs/runbooks/calagopus.md @@ -20,6 +20,7 @@ and image pins. | Game servers | `10.10.50.40:25565`–`25600` (panel allocations) | | Agent SSH (key-only, passwordless `sudo`) | `ssh -i agent@10.10.50.40`; public key in `incus/calagopus` `agent_ssh_authorized_key`, host key `SHA256:KCgI72gaW94nYPeI0a36P/xCPVbTu5AgctEjirxE1l4` | | Administrator | `admin.username` / `admin.password` in `GilmanLab/secrets` `services/calagopus/panel.sops.yaml` | +| Internet players | playit.gg tunnels, defined in the playit.gg account; agent key `playit.secret_key` in `panel.sops.yaml` | ## Preconditions @@ -64,8 +65,9 @@ If `just apply` fails with `The requested image couldn't be found`, the pinned `images:` fingerprint has expired. Pin the current `images:ubuntu/26.04/cloud` VM fingerprint in `variables.tf` and plan again. -`deliver-secrets` writes `/etc/calagopus/panel.env` and starts the stack. The -panel answers on port 8000 within about a minute. +`deliver-secrets` writes `/etc/calagopus/panel.env` and +`/etc/calagopus/playit.secret`, then starts the stack. The panel answers on +port 8000 within about a minute. ## Finish the first-run wizard @@ -128,6 +130,30 @@ start failing. - A server's console streams output in the browser, and a Minecraft client connects to its allocation. +## Open a server to internet players + +Players outside the house connect through [playit.gg](https://playit.gg). The +`playit` compose service runs the playit agent with host networking. It dials +out to playit, so neither gw01 nor rtr01 has an inbound rule, and the home IP +stays private. playit relays the traffic, which can add some latency. + +1. Turn the whitelist on before the server is public. In the server console: + `whitelist add ` for each player, then `whitelist on`. Operators join + without being listed. +2. In the playit.gg account, open the `calagopus01` agent and **Add Tunnel**: + type **Minecraft Java**, local address `10.10.50.40`, local port the + server's allocation port. Tunnel creation needs a verified email. The agent + key is read-only and cannot create tunnels through the API. +3. Give players the tunnel's address (`.joinmc.link` or the shown + `host:port`). Confirm a join from outside the house. + +One tunnel serves one server. Delete the tunnel in the playit.gg account to +close a server again. `docker logs calagopus-playit-1` on the VM shows whether +the agent is connected. + +The agent key comes from the playit.gg Docker setup wizard. To replace it, set +`playit.secret_key` in `panel.sops.yaml` and run `just deliver-secrets`. + ## Day-2 operations - **Logs**: `just logs` follows the panel and integrated Wings.