How to deploy Tsogira

The files in the repository's deploy/ directory run Tsogira on a Linux server under systemd, with Caddy in front for HTTPS. They're set up for tsogira.pbbgaming.com on Ubuntu, on the droplet that also runs Dolpher; ssh tsogira reaches it as root.

The server runs as tsogira, a system account with no login shell. Its database is /var/lib/tsogira/tsogira.db, and it listens only on 127.0.0.1:8081; Dolpher has 127.0.0.1:8080. Caddy, already installed for Dolpher, takes ports 80 and 443 for both games, gets the certificates from Let's Encrypt, and redirects HTTP to HTTPS. The DigitalOcean firewall must let 80 and 443 in.

The commands below run as root on the server, except where they say "locally".

Build

Locally, from the repository root. The binary is pure Go, so it cross-compiles without cgo:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -o tmp/tsogira-linux-amd64 ./cmd/tsogira
scp tmp/tsogira-linux-amd64 tsogira:/usr/local/bin/tsogira.new
scp deploy/tsogira.service deploy/tsogira.env deploy/tsogira.sysusers deploy/Caddyfile var/alpha/world.json tsogira:

First install

install -m 0755 /usr/local/bin/tsogira.new /usr/local/bin/tsogira && rm /usr/local/bin/tsogira.new
install -d -m 0755 /usr/local/share/tsogira
install -m 0644 world.json /usr/local/share/tsogira/world.json

install -d -m 0755 /etc/sysusers.d
install -m 0644 tsogira.sysusers /etc/sysusers.d/tsogira.conf
systemd-sysusers

install -d -m 0755 /etc/tsogira
install -m 0644 tsogira.env /etc/tsogira/tsogira.env
install -m 0644 tsogira.service /etc/systemd/system/tsogira.service

# The server never creates its database or directory.
install -d -o tsogira -g tsogira -m 0750 /var/lib/tsogira
runuser -u tsogira -- tsogira db init --db /var/lib/tsogira/tsogira.db

systemctl daemon-reload
systemctl enable --now tsogira

Then add Tsogira's site to Caddy. The Caddyfile is Dolpher's too, so append to it rather than replacing it, and check it before reloading, so a mistake can't take Dolpher down:

cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak
{ echo; cat Caddyfile; } >> /etc/caddy/Caddyfile
caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile && systemctl reload caddy

The first admin and DM

Run the CLI as tsogira, so the database stays readable by the server. It prints a single-use link; open it to set a password:

runuser -u tsogira -- tsogira invite --db /var/lib/tsogira/tsogira.db \
    --base-url https://tsogira.pbbgaming.com --admin you@example.com

An admin account's characters are DMs. To make one a master DM, who can make others with the editor, run this while the character is out of the game:

runuser -u tsogira -- tsogira master --db /var/lib/tsogira/tsogira.db NAME

Later invites and password resets also come from the CLI (tsogira invite, tsogira reset-password), with the same --db and --base-url.

Updating

After building and copying a new binary, and the world file if it changed:

install -m 0755 /usr/local/bin/tsogira.new /usr/local/bin/tsogira && rm /usr/local/bin/tsogira.new
install -m 0644 world.json /usr/local/share/tsogira/world.json
systemctl restart tsogira

The restart warns the players, reports draining on /health for TSOGIRA_DRAIN, then saves them and stops. New migrations apply when the server opens the database. Take a backup first if the update has one.

The DM editor's changes to the world are kept in the database and laid over the world file, so replacing the world file keeps them. tsogira world export prints the merged world.

What is in the rooms is saved too, so a changed world file's room contents don't appear in rooms the game has already saved. To put the world file's contents back in every room, stop the server first:

systemctl stop tsogira
runuser -u tsogira -- tsogira world reset-rooms --db /var/lib/tsogira/tsogira.db
systemctl start tsogira

Backups

The backup is safe while the server runs. The target directory must exist, and the file must not:

install -d -o tsogira -g tsogira -m 0750 /var/backups/tsogira
runuser -u tsogira -- tsogira db backup --db /var/lib/tsogira/tsogira.db \
    --to /var/backups/tsogira/tsogira-$(date -u +%Y%m%dT%H%M%SZ).db

Checking on it

systemctl status tsogira caddy
journalctl -u tsogira -f
curl -s -o /dev/null -w '%{http_code}\n' https://tsogira.pbbgaming.com/health

The log reports throttled logins (login throttled) and any panic that took a player out of the game, with its stack (panic: taking the player out of the game).