Atrium: the sync server for Cella PDF (IT guide)

Cella PDF'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.

#Self-host in 10 minutes with Docker

Atrium is one Docker container with its web server and everything else it needs built in: nothing to build or install besides 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.

cp .env.example .env
nano .env                                  # ATRIUM_DOMAIN=sync.yourfirm.com, ATRIUM_NAME=Your Firm
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: the container 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                          # "healthy"
docker compose logs -f atrium
docker compose exec atrium atrium admin rotate-token     # a new admin token
docker compose exec atrium atrium version

#TLS

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

• Public name: done; the container 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.

#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 PDF: 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 by default) 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: docker compose exec atrium atrium backup /backups --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: docker compose stop atrium && docker compose run --rm -v /path/to/backup:/backup atrium restore /backup --force && docker compose start atrium. Add --snapshot 2026-10-12 for a given day. On a new machine run docker compose run --rm atrium init too (the admin token isn't in backups). Apps that synced after the backup was taken re-send what the server is missing by themselves.

#Upgrades

Back up first, then install the new Atrium container 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; to go back, restore that copy or the backup. Clients keep working throughout.

#What is stored

Everything is in one data folder, 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 PDF 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 PDF 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 except to Let's Encrypt, to renew its certificate.

#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 PDF, 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.
• Lost the admin token: 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.
• "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: docker compose exec atrium atrium help.