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.
- Install Docker. Install Docker and its compose plugin (on Linux, Docker Engine; most NAS systems have a Docker app).
- Make a folder. Make a folder for it on the server, say
armarius. Into it, putcompose.yaml,example.envandtunnel.env.example, from thedeployfolder of the app's source on GitHub, at the version you run. - Fill in
.env. In that folder,cp example.env .envand fill it in (see The files and folders). - Make
tunnel.env.cp tunnel.env.example tunnel.env. The token goes in later. Thenchmod 600 .env tunnel.env. - Make the three folders,
data,keysandbackups(see The files and folders). On a NAS, use its steps instead. - Get your seat ready. On your desktop, be a Storyguide in the saga, and stop hosting there (see Bringing the saga in).
- Copy the saga over. Copy the saga's file and its passcode records into the
armariusfolder on the server. - Bring it in. Run the
admin saga importcommand, then delete the copied files. - Move the desktop's copy away, out of the
sagasfolder. Don't just rename it. - Make the tunnel. Create a Cloudflare tunnel, put its token in
tunnel.env, and give it the hostnamesaga.example.compointing athttp://localhost:8790(see The tunnel). - 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
keyson 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.
- 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.
- 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\armariusin Explorer once SMB is on, under Service. - Go to the folder. Sign in with SSH (
ssh YOU@NAS-ADDRESS) and runcd /volume1/armarius.ls -d /volume*/armariusfinds it. - Make the three folders.
sudo mkdir -p data keys backups, thensudo chown 10001:10001 data keys backups. - 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. - Make them private.
sudo chmod 700 data keys backups, last, since stripping the lists can reset the modes.ls -ld data keys backupsshould showdrwx------ ... 10001 10001with no+. - Protect the settings. Leave
KEYS_DIR=./keysin.env, and runsudo 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.
- 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.
- 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 thearmariusfolder on the server. The records let players keep their passcodes. Without them, every passcode must be set again. - 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. - 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.
- Delete the copies. Delete the copied files with
sudo rm, since they now belong to the app's user. - 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 listnames anyone whose passcode must still be set again (admin players set-passcode NAME, below). - Move the desktop's copy out. Move the desktop's copy of the saga file out of the
sagasfolder, for example into a folder of old copies. A change made there never reaches the server, and a copy only renamed insidesagascan 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:
- Create it. In Cloudflare's dashboard, under Networking, Tunnels (older dashboards: Zero Trust, Networks, Tunnels), create a tunnel of the cloudflared kind.
- Name it. Call it
armarius, ornas-armariusif 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. - Copy the token. Cloudflare shows a command to install it, holding a long token. Copy only the token into
tunnel.env, afterTUNNEL_TOKEN=. - Give it a hostname. Add a public hostname,
saga.example.com, whose service ishttp://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¶
- Start it. Run
docker compose up -d, or start the Project in the NAS's Docker app.docker compose psshows the app healthy within a minute. - 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. - Set passcodes.
docker exec -it armarius python main.py admin players set-passcode NAME. The-itlets it ask without showing what you type. - Issue Invites.
... admin invites issue NAMEfor each player. - Approve each device on the call, as on the desktop, with
admin invites pendingandadmin 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 inls -l). Give it to the app's user and strip them:sudo chown 10001:10001 PATH,sudo setfacl -b PATH, thensudo chmod 700 PATH(a folder) or600(a file). Check withls -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---------aftersetfacl -b. Set its modes again withsudo chmod 700 PATH. - Testing as the app's user.
sudo -ucan'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\armariuswon'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..envmissing after copying. Windows hides names starting with a dot. Turn on View, Show, Hidden items before copying.rmasks about a "write-protected" file. It belongs to the app's user now. Answery, or usesudo 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:8790as Service URL. Newer dashboards have no separate type box, since thehttp://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 intonanowith a right-click or Ctrl+Shift+V. Check without showing it:sudo awk -F= '{print NR": "$1" length="length($0)}' tunnel.envshould show oneTUNNEL_TOKENline 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 sagaslists the sagas.admin saga import FILEbrings a saga file in, checked as the app checks any saga it opens, with--passcodes FILEfor the old host's passcode records.admin saga deletedeletes one after you type its name. - Players.
admin players listsays who may have a Remote seat.admin players set-passcode NAMEasks 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(orplayer) sets a role. - The tunnel.
admin tunnel --url https://saga.example.comsets the address Invites carry.admin tunnelshows it, and where to point the tunnel. - Invites.
admin invites issue NAMEprints the Invite to send and the six words to read on the call.admin wordsprints the words again.admin invites pendinglists 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 listlists the seats, each live one with the command that revokes it.admin devices revoke IDdoes so. - The Log.
admin log, with--player NAMEor--limit N. - A new key.
admin rotate-keygives the host a new key. Restart the listener afterwards (docker compose restart armarius) so it uses it. - Backups.
admin backupputs 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, orARMARIUS_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 Nto 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.
- Install restic on the server (its website, restic.net, has the steps). On a NAS, its Docker image
restic/resticworks 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. - 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 calledcloud) withrestic -r rclone:cloud:armarius init. - Back up each night, after the backup service has run (from
cronon a Linux computer):restic -r REPOSITORY backup backups, thenrestic -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:
- Rotate the key.
docker exec -it armarius python main.py admin rotate-key, thendocker compose restart armarius. Every Invite and seat ends at once. - 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 rundocker compose up -d. - 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.
- Read the Log. Look in
admin logfor 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:
- Read its notes on the Releases page.
- Take a backup with
admin backup. - Set the version. Set
ARMARIUS_VERSIONin.envto it. - Pull and restart.
docker compose pull, thendocker 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.