Skip to content

How to self-host a saga

Your players want to fill in their seasons on a Tuesday night, when your own computer is off. A server or NAS that's always on can host the saga for them, day and night.

It hosts one saga for Remote seats, players joining from their own Armarius over the internet. It runs the app's container image with no window: the listener for Remote seats, and beside it a tunnel that brings players in. Nothing on the server is opened to the internet, since the tunnel connects out. You look after it with the admin command, in a terminal on the server.

Only Remote seats are hosted this way, so players need Armarius on their own computers. Hosting for browsers and SSH stays on your desktop, until the app can cap how many copies a host runs for them.

You'll need the server or NAS, with Docker and its compose plugin, a domain on Cloudflare for the tunnel (or Tailscale, below), the saga's file from your desktop, and a terminal on the server over SSH. The steps use the example address saga.example.com. Use your own.

The recipe below works anywhere Docker runs. On a NAS, run each docker command as sudo docker, and see A UGREEN NAS for the steps that differ.

  1. Install Docker. Install Docker and its compose plugin (on Linux, Docker Engine; most NAS systems have a Docker app).
  2. Make a folder. Make a folder for it on the server, say armarius. Into it, put compose.yaml, example.env and tunnel.env.example, from the deploy folder of the app's source on GitHub, at the version you run.
  3. Fill in .env. In that folder, cp example.env .env and fill it in (see The files and folders).
  4. Make tunnel.env. cp tunnel.env.example tunnel.env. The token goes in later. Then chmod 600 .env tunnel.env.
  5. Make the three folders, data, keys and backups (see The files and folders). On a NAS, use its steps instead.
  6. Get your seat ready. On your desktop, be a Storyguide in the saga, and stop hosting there (see Bringing the saga in).
  7. Copy the saga over. Copy the saga's file and its passcode records into the armarius folder on the server.
  8. Bring it in. Run the admin saga import command, then delete the copied files.
  9. Move the desktop's copy away, out of the sagas folder. Don't just rename it.
  10. Make the tunnel. Create a Cloudflare tunnel, put its token in tunnel.env, and give it the hostname saga.example.com pointing at http://localhost:8790 (see The tunnel).
  11. Start it. docker compose up -d, then tell it the tunnel's address and issue the Invites (see Starting it).

The files and folders

In .env, set ARMARIUS_VERSION, the version to run, such as 4.13.0. Always give a number, never "latest". Set ARMARIUS_SAGA to the saga's id, which is the name of its file in your save folder's sagas, without .json.

The three folders, data, keys and backups, are owned by the app's own user (number 10001) and private to it:

sudo install -d -o 10001 -g 10001 -m 700 data keys backups

keys holds the host key. An encrypted disk or volume is the best home for it (set KEYS_DIR in .env to it). A NAS's encrypted shared folder will do if the app's user can use it: try it first, and if it can't, use a plain private folder instead. UGOS's can't (see A UGREEN NAS).

The compose file runs the app locked down. It runs as its own user, with its system files read-only, no extra privileges, 512 MB of memory at most, and no port published.

A Linux computer or rented server

Any always-on Linux computer will do, such as an old laptop, a mini PC, a Raspberry Pi 4 or 5 (the image has an ARM version), or the smallest server a hosting company rents. One processor and 1 GB is plenty.

  • Docker. Install Docker Engine and the compose plugin, following Docker's own guide for your system (docs.docker.com, Install Docker Engine).
  • The key at home. On a home computer, put keys on an encrypted disk if the system offers one.
  • A rented server. Its company can read its disks, so the key is safer at home. If you rent one anyway, choose one with disk encryption, and let no one else onto it. Close every port in its firewall but SSH. The tunnel needs none.

Then follow the recipe above.

A UGREEN NAS

A UGREEN NAS runs it in the Docker app of UGOS Pro. Docker picks the image's version for the NAS's processor (amd64 for Intel, arm64 for ARM), and the app uses at most 512 MB of memory. The steps follow UGOS Pro 1.21, and menu names may move in later versions.

  1. Turn on SSH. In Control Panel, Service, turn on SSH (Terminal), port 22. Set it to turn itself off after a few hours, since you only need it while setting up and for admin chores.
  2. Make the shared folder. In the Files app, make an ordinary shared folder, armarius, and copy the three files into it. The Files app's upload works, and so does \\NAS-ADDRESS\armarius in Explorer once SMB is on, under Service.
  3. Go to the folder. Sign in with SSH (ssh YOU@NAS-ADDRESS) and run cd /volume1/armarius. ls -d /volume*/armarius finds it.
  4. Make the three folders. sudo mkdir -p data keys backups, then sudo chown 10001:10001 data keys backups.
  5. Strip UGOS's access lists. sudo setfacl -b data keys backups. UGOS shows these lists as a + after the modes. They open a folder to every NAS account, and the app refuses a key folder others can open.
  6. Make them private. sudo chmod 700 data keys backups, last, since stripping the lists can reset the modes. ls -ld data keys backups should show drwx------ ... 10001 10001 with no +.
  7. Protect the settings. Leave KEYS_DIR=./keys in .env, and run sudo chmod 600 .env tunnel.env.

Not UGOS's encrypted shared folders, for the keys. They look like the right home for a key, but the app's user can't use one. UGOS mounts it as a filesystem of its own (fuse.uggocryptfs) that answers user 10001 with "Input/output error". It reports every folder in it as open to all (rwxrwxrwx) whatever its modes, and stripping its access lists sets it to no access at all. Keep the keys in the ordinary keys folder above, private to the app's user. What that gives up: someone who steals the NAS's drive could read the key, and then you'd rotate it and send everyone a new Invite.

Over SSH, sudo docker compose ... works from the armarius folder, and the Docker app's Project view shows the same containers.

Bringing the saga in

The saga moves to the server, and your desktop's copy becomes history.

  1. Be a storyguide in it. On your desktop, make sure you're a Player in the saga with the Storyguide role and a passcode of 14 characters or more. You'll join your own saga from the desktop like everyone else. Stop hosting there.
  2. Copy two files. From your save folder, copy the saga's file, in sagas, and its passcode records, remote/NAME-passcodes.json (NAME being the saga's name), into the armarius folder on the server. The records let players keep their passcodes. Without them, every passcode must be set again.
  3. On a NAS, hand them over. Files copied in belong to your NAS account and its access lists, which the app's user can't read ("Permission denied"). Give them to it first: sudo chown 10001:10001 FILES, sudo setfacl -b FILES, sudo chmod 600 FILES.
  4. Import them. Run the command below, with your own file names. The saga is checked as the app checks any saga it opens. A passcode record comes over only for the very passcode it was made for, so one for a passcode changed since is dropped.
  5. Delete the copies. Delete the copied files with sudo rm, since they now belong to the app's user.
  6. Issue new Invites. The server makes a host key of its own, so every Invite and seat from your desktop has ended. Issue everyone a new Invite, your own desktop's storyguide seat included. admin players list names anyone whose passcode must still be set again (admin players set-passcode NAME, below).
  7. Move the desktop's copy out. Move the desktop's copy of the saga file out of the sagas folder, for example into a folder of old copies. A change made there never reaches the server, and a copy only renamed inside sagas can save itself back under the saga's own name.

The import command:

docker compose run --rm -v "$PWD/SAGA.json:/in/saga.json:ro" -v "$PWD/NAME-passcodes.json:/in/passcodes.json:ro" armarius admin saga import /in/saga.json --passcodes /in/passcodes.json

The tunnel

Cloudflare Tunnel, the compose file's own:

  1. Create it. In Cloudflare's dashboard, under Networking, Tunnels (older dashboards: Zero Trust, Networks, Tunnels), create a tunnel of the cloudflared kind.
  2. Name it. Call it armarius, or nas-armarius if your desktop already has a tunnel. Give the server its own tunnel, never a second connector on the desktop's, or Cloudflare would share players between the two hosts.
  3. Copy the token. Cloudflare shows a command to install it, holding a long token. Copy only the token into tunnel.env, after TUNNEL_TOKEN=.
  4. Give it a hostname. Add a public hostname, saga.example.com, whose service is http://localhost:8790. The tunnel shares the app's network, so "localhost" is the app.

Whoever has the token can serve your saga's address, so keep tunnel.env like the key. Where to go: developers.cloudflare.com, Cloudflare Tunnel.

Tailscale Funnel instead, with no domain needed. In the compose file, put a tailscale/tailscale service in place of cloudflared, with the same network_mode: "service:armarius", an auth key in its own env file, and a Funnel serve setting that sends https:// traffic to http://127.0.0.1:8790. Tell the listener which tunnel it's behind. Give the armarius service command: ["seats", "--tunnel", "other"] and run admin tunnel --tunnel other. Where to go: tailscale.com/docs, Tailscale in Docker and Tailscale Funnel.

Starting it

  1. Start it. Run docker compose up -d, or start the Project in the NAS's Docker app. docker compose ps shows the app healthy within a minute.
  2. Give it the address. Tell it the tunnel's address, which Invites carry: docker exec armarius python main.py admin tunnel --url https://saga.example.com.
  3. Set passcodes. docker exec -it armarius python main.py admin players set-passcode NAME. The -it lets it ask without showing what you type.
  4. Issue Invites. ... admin invites issue NAME for each player.
  5. Approve each device on the call, as on the desktop, with admin invites pending and admin approve ID.

If it won't start, docker compose logs armarius shows what the app said. It names what's wrong, such as a key folder others can read or a saga it can't find.

When a step goes wrong

  • "Permission denied" reading a file, or a key folder refused as open to others. It's the NAS's own access lists (a + after the modes in ls -l). Give it to the app's user and strip them: sudo chown 10001:10001 PATH, sudo setfacl -b PATH, then sudo chmod 700 PATH (a folder) or 600 (a file). Check with ls -ld PATH.
  • "The key folder ... isn't there". The app never makes the key folder itself, so that a volume not yet unlocked, after a restart say, can't be given a fresh key in its place. Unlock the volume, or, the first time, make the folder as the message says.
  • "Input/output error" or "Not a directory" in the keys folder. It's an encrypted shared folder of the NAS's that the app's user can't use (as on UGOS). Use a plain private folder instead (see A UGREEN NAS).
  • A folder shows d--------- after setfacl -b. Set its modes again with sudo chmod 700 PATH.
  • Testing as the app's user. sudo -u can't, since the NAS has no account 10001. Ask the image instead: sudo docker run --rm --user 10001:10001 -v PATH:/keys --entrypoint sh armarius:VERSION -c 'ls -lnd /keys; touch /keys/t && ls -ln /keys/t; rm -f /keys/t'.
  • \\NAS-ADDRESS\armarius won't open in Explorer. The shared folder doesn't exist yet, or Windows file sharing (SMB) is off on the NAS. Upload through the NAS's Files app instead.
  • .env missing after copying. Windows hides names starting with a dot. Turn on View, Show, Hidden items before copying.
  • rm asks about a "write-protected" file. It belongs to the app's user now. Answer y, or use sudo rm.
  • Where's the tunnel's token? On the tunnel's setup page choose Docker as the system. The command shown ends with the token, which starts eyJ. Copy only the token, and don't run the command, since the compose file runs cloudflared. The page's Continue button stays grey until the server connects, so add the public hostname after starting it.
  • The tunnel shows Healthy but "No routes". Open it and add a route (Routes, Add route, Published application), with the hostname, and http://localhost:8790 as Service URL. Newer dashboards have no separate type box, since the http:// says it. Until the route exists the address has no DNS record, and a player's Join says to check the storyguide is hosting.
  • Add the route before anyone tries to join. A home router remembers "no such name" for up to half an hour, even after the route exists. To tell that apart from a broken tunnel, ask Cloudflare's own DNS (nslookup NAME 1.1.1.1). If it answers there, only the router's memory is in the way, so wait or restart the router.
  • The token didn't save in tunnel.env. In Windows Terminal, paste into nano with a right-click or Ctrl+Shift+V. Check without showing it: sudo awk -F= '{print NR": "$1" length="length($0)}' tunnel.env should show one TUNNEL_TOKEN line of about 200 characters. 13 means it's empty.

Looking after it with the admin command

A host with no screen does what the Host for Players window does with the admin command, typed in a terminal on that computer. In a container, that's docker exec -it armarius python main.py admin ..., and from a source checkout uv run python main.py admin .... It reads and writes the saga's files there, and nothing goes over the network.

--saga names the saga by its id or name. With only one saga, or ARMARIUS_SAGA set, it can be left out. admin --help lists everything, and --help after any word says more.

  • Sagas. admin sagas lists the sagas. admin saga import FILE brings a saga file in, checked as the app checks any saga it opens, with --passcodes FILE for the old host's passcode records. admin saga delete deletes one after you type its name.
  • Players. admin players list says who may have a Remote seat. admin players set-passcode NAME asks for a new passcode twice, without showing it. It's never typed on the command line, where others could see it. admin players set-role NAME storyguide (or player) sets a role.
  • The tunnel. admin tunnel --url https://saga.example.com sets the address Invites carry. admin tunnel shows it, and where to point the tunnel.
  • Invites. admin invites issue NAME prints the Invite to send and the six words to read on the call. admin words prints the words again. admin invites pending lists what waits: who asks, from which device, and its three words to check on the call. Under each is the exact command that approves it or turns it down, ready to copy, with a short form of the request's id.
  • Seats. admin devices list lists the seats, each live one with the command that revokes it. admin devices revoke ID does so.
  • The Log. admin log, with --player NAME or --limit N.
  • A new key. admin rotate-key gives the host a new key. Restart the listener afterwards (docker compose restart armarius) so it uses it.
  • Backups. admin backup puts the saga and its Remote seat files (Invites, seats, the Log, the tunnel address) into one zip in the backups folder, named for the saga and the time. Give the folder with --to FOLDER, or ARMARIUS_BACKUPS, which the container sets to /backups. It's safe while players play, since each file is copied whole, between saves. It keeps the newest 30 (--keep N to change that) and never holds the host key. To restore, unzip it into the data folder with the listener stopped.

Anything that changes a seat asks first. Add --yes to skip the question in a script. The checks are the window's own, so a passcode under 14 characters, an Invite for a player with no passcode, or an approval of a request that has lapsed is refused the same way.

The host key on a server

On a desktop the host key lives in the computer's keychain. A server with no screen has none, so the app keeps it in a file instead, but only when told to: ARMARIUS_KEYSTORE=file, with ARMARIUS_KEYS naming the folder (/keys if left out). The container image sets both, and a desktop never needs them.

The folder must be one of its own, never inside the data folder, so the keys never travel with the saga or its backups. Only the app's own user may open it. The app refuses to start if anyone else can read the folder or a key in it, if it belongs to another user, or if the app runs as the administrator (root).

Whoever can read that folder can pretend to be your host. On a NAS that's its administrators, and anyone who may run Docker there.

Where to keep it:

  • A private folder of its own. Outside the data folder, owned by the app's user (10001) with modes 700, and with any NAS access lists stripped (sudo setfacl -b FOLDER). That much is required: the app refuses anything less.
  • Encrypted, where the server can. A disk or volume the system encrypts protects the key if someone takes the server's drives. A NAS's encrypted shared folder works too, if the app's user can read and write it. Try it first (When a step goes wrong has a test). On UGOS it can't (see A UGREEN NAS), so use a plain private folder there.
  • What a plain folder gives up. It keeps the key from everyone on the server but its administrators, but not from someone who steals the drives. They could read it, and you would rotate it and send everyone a new Invite (see If the key or the token leaks).

Back the keys folder and tunnel.env up apart from the nightly backups, which never hold them (see Backups off the server).

When it refuses, it says the fix. That's sudo chown 10001:10001 FOLDER for a folder made by another user, as a NAS's web pages make them, and chmod 700 for the folder or chmod 600 for a key others can read. For root, start it as the image's own user (no user: root).

Backups off the server

On the server, every night. The compose file's backup service runs admin backup when the project starts and then once a day, keeping the newest 30. BACKUP_EVERY, in seconds, and BACKUPS_KEPT in .env change that. It needs no scheduler on the server, never sees the keys, and has no network. docker compose logs backup shows each one, and the zips are in backups.

A NAS's own snapshots of the armarius folder are a good extra, but they stay on the same disks. They hold the keys folder too, so never copy them off the NAS.

Off the server. admin backup keeps copies on the server, and a second copy elsewhere survives the server. restic does it well. It encrypts everything before it leaves the server, so the copy can sit on your desktop or in a cloud folder.

  1. Install restic on the server (its website, restic.net, has the steps). On a NAS, its Docker image restic/restic works the same way. Keep its password in a file only you can read (chmod 600), and a copy of it somewhere safe. Without it the backups can't be opened.
  2. Make a repository. On your desktop, over SSH: restic -r sftp:you@desktop:/backups/armarius init. In a cloud drive such as Dropbox or Google Drive, go through rclone (rclone.org, after setting up a remote called cloud) with restic -r rclone:cloud:armarius init.
  3. Back up each night, after the backup service has run (from cron on a Linux computer): restic -r REPOSITORY backup backups, then restic -r REPOSITORY forget --keep-daily 14 --keep-weekly 8 --prune.

Back the keys folder and tunnel.env up apart, to a different restic repository with a different password, or not at all. A lost key costs only new Invites for everyone, while a leaked one lets someone pretend to be your host.

If the key or the token leaks

If the keys folder, tunnel.env, or a backup of either may have been seen by someone else:

  1. Rotate the key. docker exec -it armarius python main.py admin rotate-key, then docker compose restart armarius. Every Invite and seat ends at once.
  2. Replace the token. In Cloudflare's dashboard, make the tunnel a new token, or delete the tunnel and make another. Put it in tunnel.env, then run docker compose up -d.
  3. Invite everyone again. Issue everyone a new Invite, your own desktop's seat included, and read each of them the new six words on a call.
  4. Read the Log. Look in admin log for sign-ins from before you rotated that you don't recognise.

A newer version

The server never updates itself, and never checks for an App update: the image sets ARMARIUS_UPDATES=off. Your own desktop still tells you when a newer version is out (see How to check for an App update). To move the server to a newer version:

  1. Read its notes on the Releases page.
  2. Take a backup with admin backup.
  3. Set the version. Set ARMARIUS_VERSION in .env to it.
  4. Pull and restart. docker compose pull, then docker compose up -d.

Within the same first number (4.13 to 4.14, say) seats keep working, though a player on another version is told the two haven't been tested together. A new first number (5.0) means every player moves to it too, since a seat refuses a host of another major version.

See also: How to host a saga And: Remote seats: hosting safely, which a self-hosted saga follows too.