Operator Handbook

This page is the short operator route through the maintained single-host Compose deployment. Use the repository runbook for exact commands and paths; run them from deploy/ with the same Compose file that created the stack.

First claim

Danger

Protect /setup from untrusted visitors, then claim it immediately. The first visitor owns the pre-generated administrator account linked to #1.

After claim, verify a fresh administrator login, an ordinary telnet login, the portal terminal over wss://your-domain/ws, readiness, logs, private metrics, and wizard-only @storage output.

What recovery actually covers

World copies

@backup asks LMDB for a point-in-time world copy. Never let a file backup read live data.mdb.

Wiki assets

Uploaded files live outside the LMDB world and must be included separately in Restic snapshots.

NATS state

JetStream persistence supports bounded replay and WebSocket recovery; it is not a world backup.

Plugins and config

Preserve plugin files and deployment config. Keep .env values in a separate secrets system.

Restore rehearsal

1. Restore a dated Restic snapshot to an isolated directory or host, never over the live volume.
2. Start a non-public stack with test-only secrets and no production DNS, mail, bots, or automation.
3. Check known dbrefs, administrator and player login, core softcode, mail/channels, wiki assets, plugins, telnet, and the browser terminal.
4. Record the snapshot id, recovery time, recovered scope, evidence, failures, and corrections.

Upgrade and incident rules

Keep the deployment’s documented image and automatic-update policy. Before deliberate change, record current image digests, take a fresh world copy, confirm storage headroom, and read the connection impact. Replacing the engine or renderer can preserve game sockets; replacing SocketServer closes them. Deployment rollback restores binaries/configuration. Data recovery restores persistent state. Do not substitute one for the other.

Start incidents with readiness, bounded logs, metrics, @storage, service restart history, image digests, and the affected connection path. Never publish .env, passwords, cookies, bearer/resume tokens, Restic credentials, or connection strings in diagnostics.

Full operator runbook State-by-state backup coverage, exact checks, rollback distinctions, and incident triage.

Deployment commands Compose files, ports, backups, storage planning, restore commands, and Cloudflare setup.

Deployment architecture Service ownership, protocols, persisted state, and restart boundaries.