Atrium: the sync server for Cella (IT guide)

Cella's Sync menu keeps a project's drawings and everyone's markups in step across the office: people draw on the same sheet and see each other's markups arrive live, with every change kept as history. Sheet changes travel too: a sheet turned, moved, inserted, deleted or renamed on one computer changes on everyone's, and so do the custom columns, sequences, revision schedule and bookmarks, and each sheet's scales, scale regions, hyperlinks and Spaces. The server behind it is Atrium: a shared hub for the firm's drawings. This guide is for whoever sets it up.

There are two ways to have one:

Hosted firms can skip to Inviting people. Everything else here is for self-hosting. (Developer and protocol detail: sync/README.md; security: sync/SECURITY.md.)

Status for 1.0: the server, its binaries and its tests are run and passing. The Docker image, compose file and systemd unit were written and checked by hand but not yet run on a Docker host or a Linux server; please tell Sorted Solution how the first install goes.

#Self-host in 10 minutes with Docker

You need: a Linux machine (a small VM is plenty) with Docker Engine and the compose plugin 2.20 or newer, a DNS name for it (sync.yourfirm.com), and ports 80 and 443 reachable from wherever people work. Port 80 is only for the certificate.

git clone <the Cella repository> && cd cella/sync      # or unpack the release's sync/ folder
cp .env.example .env
nano .env                                  # ATRIUM_DOMAIN=sync.yourfirm.com, ATRIUM_NAME=Your Firm
docker compose build                       # about two minutes
docker compose run --rm atrium init        # prints the admin token ONCE: put it in your password manager
docker compose up -d

Open https://sync.yourfirm.com/admin and sign in with the token. That's it: Caddy fetched a certificate, Atrium is running as a non-root user with its data in the atrium-data volume, and a backup runs every night at 03:00 UTC into the atrium-backups volume.

Useful afterwards:

docker compose ps                          # both "healthy"
docker compose logs -f atrium
docker compose exec atrium atrium admin rotate-token     # a new admin token
docker compose exec atrium atrium version

#One binary (Linux, Windows, macOS)

Each release has a self-contained atrium for linux-x64, linux-arm64, win-x64 and osx-arm64: no .NET or anything else to install. (Build them yourself with sync/publish.sh.)

tar -xzf atrium-1.0.0-linux-x64.tar.gz && cd atrium-1.0.0-linux-x64
./atrium init --data /srv/atrium            # prints the admin token once
./atrium serve --data /srv/atrium --name "Your Firm"

On Windows: atrium.exe init --data D:\Atrium then atrium.exe serve --data D:\Atrium. To keep it running without a logged-in user, wrap it as a service with a tool such as NSSM (nssm install Atrium C:\Atrium\atrium.exe serve --data D:\Atrium); a native Windows service mode isn't in 1.0. On a Mac mini, a LaunchDaemon (/Library/LaunchDaemons/com.sortedsolution.atrium.plist with ProgramArguments atrium serve --data /Library/Atrium, RunAtLoad and KeepAlive true, run as a dedicated user) does the same; a binary built elsewhere needs codesign -s - atrium first.

#Linux with systemd

deploy/atrium.service (also in each Linux archive) runs Atrium as its own user with a locked-down sandbox. Settings go in /etc/atrium/atrium.env.

sudo useradd --system --home-dir /var/lib/atrium --shell /usr/sbin/nologin atrium
sudo install -m 0755 atrium /usr/local/bin/atrium
sudo install -d -m 0750 -g atrium /etc/atrium
sudo install -m 0640 -g atrium atrium.env.example /etc/atrium/atrium.env    # edit: ATRIUM_NAME, …
sudo install -d -m 0700 -o atrium -g atrium /var/lib/atrium /var/cache/atrium /var/backups/atrium
sudo -u atrium atrium init --data /var/lib/atrium                            # the admin token, once
sudo install -m 0644 atrium.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now atrium
journalctl -u atrium -f

The example settings bind Atrium to 127.0.0.1:8787 for a reverse proxy on the same machine (next section) and turn on nightly backups into /var/backups/atrium.

#TLS

Every request carries a person's token, so use HTTPS for anything beyond a trusted office LAN.

• Docker: done; Caddy gets and renews a Let's Encrypt certificate (and adds HSTS).
• Office-only name with no public DNS (sync.yourfirm.local): in .env set ATRIUM_CADDY_TLS=tls internal (Caddy's own certificate authority: install its root, from the caddy-data volume, on each computer) or mount your own certificate into Caddy and set ATRIUM_CADDY_TLS=tls /certs/fullchain.pem /certs/privkey.pem.
• Caddy on the same machine as the binary:

  sync.yourfirm.com {
      reverse_proxy 127.0.0.1:8787 { flush_interval -1 }
  }

  with ATRIUM_BIND=127.0.0.1 and ATRIUM_TRUST_PROXY=127.0.0.1.

• nginx: turn buffering off for the live event stream, allow long reads and big uploads, and pass the client address:

  location / {
      proxy_pass http://127.0.0.1:8787;
      proxy_set_header Host $host;
      proxy_set_header X-Forwarded-For $remote_addr;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_http_version 1.1;
      proxy_buffering off;
      proxy_read_timeout 1h;
      client_max_body_size 2g;
  }

• Atrium itself: ATRIUM_TLS_CERT=/etc/atrium/fullchain.pem and ATRIUM_TLS_KEY=…/privkey.pem (PEM). Restart it after renewing the certificate.

#Inviting people

1. Sign in at https://<your address>/admin with the admin token.
2. Projects ▸ Create: name it like the job (2417 Riverside Clinic).
3. Invites ▸ Create invite for the project, with a note (Sam's laptop). Copy the code (J6GV-0WDS-ZJ3B); it is shown once, works once, and lasts 14 days.
4. Send each person the address and their code. In Cella: Sync ▸ Join a Sync Server…, enter both, then Sync ▸ Connect Document… on a sheet.

Each device that joins gets its own token (kept in the Mac's Keychain, Windows' DPAPI or Linux's secret service). Members ▸ Remove takes someone out of a project. A lost laptop: atrium admin devices, then atrium admin revoke-device <id>; its token stops working everywhere. Headless setups can do it all from the command line: atrium admin create-project, atrium admin invite <project> --note ….

Also on the admin page. Under Projects, each project's tools and client ids disclosure shows its Project Tools (how many, who changed them last) with Clear Project Tools, and the app install ids its members hold with Release (for a reinstalled or replaced machine whose id someone else's device should take over). Streams shows live documents per device against the cap and who is present on which document; Database the schema version, size, last backup and the atrium.db.before-vN copies an upgrade left; the Audit log lists token rotations, revoked devices, cleared Project Tools and released ids. /admin/metrics carries the stream and presence counts too.

Project Tools. Everyone in a project can share tools from their Tool Chest with the whole project (Tool Chest ▸ Manage Tool Chest… ▸ Project Tools ▸ Share with Project…); they appear under Tool Chest ▸ Project Tools on every member's computer while a document of the project is open. Atrium has no roles inside a project (only the admin token and members), so any member can change or remove them; each change records who made it. Last change wins; someone whose change was replaced at the same moment is told.

#Backups

• Built in: ATRIUM_BACKUP_DIR (on in the Docker setup) takes a consistent backup every night at ATRIUM_BACKUP_HOUR (UTC) and keeps ATRIUM_BACKUP_KEEP (14) dated database snapshots; the PDFs in it are shared between them, so it costs little more than one copy. The admin page shows when it last ran.
• By hand or from cron: atrium backup /backups/atrium --keep 14 (safe while running).
• Offsite: copy the backup folder off the machine every night (restic, rclone, your NAS's backup). A backup on the same disk is not a backup. A backup is the whole server (every PDF and the database): Atrium creates a new backup folder readable by its own user only; keep it that way.
• Restore: stop Atrium, then atrium restore /backups/atrium --force (the latest) or --snapshot 2026-10-12 (that day) and start it. On a new machine run atrium init too (the admin token isn't in backups). With Docker: docker compose stop atrium && docker compose run --rm -v /path/to/backup:/backup atrium restore /backup --force && docker compose start atrium. Apps that synced after the backup was taken re-send what the server is missing by themselves.

#Upgrades

Back up first, then replace the binary (or git pull && docker compose build && docker compose up -d) and start it. A release that changes the database migrates it on first start, after copying it to atrium.db.before-v<N> in the data folder. An older Atrium refuses to open a newer database; to go back, restore that copy or the backup. Clients keep working throughout: the protocol is versioned. 1.0 speaks protocols 1 and 2: version 2 carries sheet changes and document settings, and a Cella that only knows version 1 keeps syncing markups (it doesn't see sheet changes; update it to get them). A sheet's scales, scale regions, hyperlinks and Spaces need this release's Atrium on top: with an Atrium 1.0 from before 2026-10-15 they stay on each computer, as before, and nothing else changes. Going from a server that only knew version 1 to 1.0 converts the database once (schema 1 to 2: the existing markup history is kept and tagged with the sheet each markup was on); a copy from before stays in atrium.db.before-v2. The 1.0 release also adds schema 3 (which member each app install's id belongs to, filled from the existing history) and schema 4 (Project Tools, a project's shared Tool Chest group, below; the copy from before is atrium.db.before-v4): an older Atrium doesn't offer Project Tools and Cella shows none.

#What is stored

Everything is in one data folder (/var/lib/atrium, or the atrium-data volume):

• atrium.db: projects; members (name, email, when they joined, last seen, a hash of each device's token); invite codes (hashed); every markup change (the markup's own data: type, position, text, author, status, replies) and every sheet change (turned, moved, inserted, deleted, renamed) and change to a document's custom columns, sequences, revision schedule or bookmarks or to a sheet's scales, hyperlinks or Spaces, and each project's shared tool set (Project Tools: the tools' names, styles and any stamp pictures, at most 500 tools and 2 MB), each with who made it and when. Nothing is ever deleted from this history.
• blobs/: every version of every PDF uploaded to a project, and pages inserted into a synced document.
• admin-token.sha256: a hash of the admin token.

No passwords, no payment details, no telemetry: Atrium never contacts anyone. Presence (who has which sheet open, their pointer) is kept in memory only. Atrium doesn't encrypt its files; keep the folder and its backups on an encrypted disk.

On each person's computer, beside a synced PDF, Cella keeps a hidden .cella folder: the link to the project with the changes not yet sent (<file>.sync.json), and the pages inserted while the server couldn't be reached (<file>.sync-queue/, up to 64 MB) until they upload, so quitting Cella offline loses nothing. The queue empties and the pages go once the server has them; the member token is in the system keychain, never there.

#Firewall and ports

Atrium makes no outgoing connections. Caddy contacts Let's Encrypt to renew certificates.

#Sizing

Small. A firm of 5 to 50 people should run comfortably on 1 to 2 CPUs and 1 to 2 GB of memory (an estimate; the work is relaying small JSON messages and serving PDFs). Disk is the drawings: every uploaded version of every PDF is kept, so plan for roughly twice the size of the firm's current drawing sets plus growth, and the same again for local backups. One live session is one open connection per person per open sheet.

#Monitoring

• GET /health answers { "ok": true } (no token; Docker's health check uses it via atrium health).
• GET /admin/metrics (Prometheus text) with the admin token, or with ATRIUM_METRICS_TOKEN, a token that reads metrics and nothing else: projects, documents, ops, connected clients, storage bytes, seats, last backup time and success.

#Troubleshooting

• The app says it can't reach the server: curl https://<address>/api/v1/info from that computer should print the server's name, "protocol":1 and "protocols":[1,2].
• "Sheets can't be changed on this sync server": the server is an older Atrium that keeps only markups. Upgrade it (above); the apps pick it up on their next connect.
• "Your sheet change wasn't sent": someone uploaded a newer version of that document; in Cella, Sync ▸ Update Sheets from Project, then make the change again. Nothing of the refused change reaches the project: a refused sheet delete doesn't take that sheet's markups away for anyone else.
• "Can't undo: that sheet was deleted by …": the step you undid (or redid) was for a sheet someone else deleted meanwhile; it is skipped and taken off your Undo history. Undo / Redo of sheet changes otherwise work while synced: each sends the inverse change, so everyone's copy follows.
• "A sheet you chose was deleted … while the dialog was open": someone else deleted a sheet while your Delete, Move To, Insert Pages or Extract Sheets dialog was up, so nothing was changed; choose the sheets again. (Sheets someone else only moved meanwhile are found where they are now.)
• "Not updated: “A-201”…" after Update Sheets: that sheet was deleted or renumbered in the project while the confirm was up; the other sheets were updated.
• Live updates arrive late or in bursts: a proxy is buffering; see the nginx settings above (Caddy needs flush_interval -1).
• Lost the admin token: atrium admin rotate-token on the server (docker compose exec atrium atrium admin rotate-token).
• "read-only" banner: only on Sorted Solution-hosted instances whose plan has ended; renew with Sorted Solution.
• Uploads fail over a certain size: raise ATRIUM_MAX_UPLOAD_MB and the proxy's body limit.
• "This device has 32 live documents open on this server already": one computer has more synced documents open at once than ATRIUM_MAX_STREAMS_PER_DEVICE (32) allows; close some, or raise it.
• Someone removed from a project still sees changes for a moment: an open document stops getting them within the keep-alive interval (ATRIUM_KEEPALIVE_SECONDS, 20 s), and it can't reconnect. A lost computer: atrium admin revoke-device ID (atrium admin devices lists them).
• All settings: sync/README.md ▸ Settings, or atrium help.