Operations
The commands here assume the bundled docker-compose.yml, run from its
directory. With docker run, use docker exec compass-sync ... and
docker logs compass-sync instead.
Backups
Section titled “Backups”The server backs itself up. Once a day it writes a consistent,
compacted copy of its database to /data/backups in its volume, named
compass-sync-<UTC time>.db, and keeps the newest 7. The first one is made
at start if the newest on disk is older than a day. Change it with
COMPASS_SYNC_BACKUP_INTERVAL, COMPASS_SYNC_BACKUP_KEEP and
COMPASS_SYNC_BACKUP_DIR (Configuration).
These sit on the same disk as the database, so copy them elsewhere now and then (rsync, restic, your provider’s snapshots). To find them on the host:
docker volume inspect -f '{{ .Mountpoint }}' compass-sync_sync-dataA copy on demand. Ask the running server for one, which is safe at any time:
docker compose exec -T sync /compass-sync-server backup - > compass-sync-$(date +%F).db-T matters: without it the terminal mangles the bytes. A cron job running
that line, plus copying the file off the machine, is a complete backup
plan.
Restore
Section titled “Restore”As root (the volume’s directory belongs to root), in the directory with
docker-compose.yml:
docker compose stop synccd "$(docker volume inspect -f '{{ .Mountpoint }}' compass-sync_sync-data)"mkdir -p replaced && mv compass-sync.db* replaced/ # the db, -wal and -shmcp backups/compass-sync-20261031T220000Z.db compass-sync.dbchown 65532:65532 compass-sync.db # the image's usercd - && docker compose start synccurl -fsS https://sync.example.com/healthzDevices carry on from where the backup was: changes made after it come
back as the devices upload them again, and devices that synced later may
show those changes as conflicts they resolve themselves. Delete replaced/
once all is well.
Upgrading
Section titled “Upgrading”docker compose pulldocker compose up -dThe server updates its database on start; there’s nothing to migrate by
hand. To stay on a known build, use a sha-<short commit> tag of the image
instead of latest.
A server never opens a database written by a newer version: it refuses to
start (database schema N is newer than this server). So you can’t go back
to an older image after an upgrade changed the database, unless you restore
a backup made before it. Take one before upgrading
(backup -, above) if you may want to go back.
Restarting closes the devices’ open connections; they reconnect within seconds.
Monitoring
Section titled “Monitoring”/healthzanswersokwhen the server runs and its database answers,503otherwise. The container’s health check uses it (docker compose psshowshealthy). Point an uptime checker athttps://sync.example.com/healthz./health-checkanswers JSON with the server’s version, commit and build time./metrics: withCOMPASS_SYNC_METRICS: "1", Prometheus metrics (requests, database calls, Go runtime).
docker compose logs -f syncdocker compose logs --since 1h syncThe server logs JSON lines; refused requests show as
Authorization failed with the reason.
Limits and expiry
Section titled “Limits and expiry”Each chain may store COMPASS_SYNC_MAX_ENTITIES items (100,000) and
COMPASS_SYNC_MAX_BYTES bytes (200 MiB), and at most
COMPASS_SYNC_MAX_HISTORY history items (30,000) from the last
COMPASS_SYNC_HISTORY_DAYS (14). A chain may have up to 50 devices.
- A device that hits the item or byte limit keeps its data. Compass shows “Sync: server full” in its menu and sync settings.
- At the history limit, other data keeps syncing and new visits stay on the device they were made on; Compass shows “History full”.
Expiry runs every hour:
- History older than
COMPASS_SYNC_HISTORY_DAYSis deleted from the server (the devices keep their own). - Deletions are remembered for
COMPASS_SYNC_TOMBSTONE_DAYS(30) so devices that were away learn of them. - A chain none of whose devices has connected for
COMPASS_SYNC_IDLE_CHAIN_DAYS(180) is deleted. A device that comes back later is told to stop syncing; its own data stays, and it can start sync again.
Troubleshooting
Section titled “Troubleshooting”curl https://sync.example.com/healthz fails. Check docker compose ps
and docker compose logs caddy: most often the DNS record doesn’t point at
the machine yet, or port 80 or 443 is closed, so Caddy can’t get a
certificate. Invalid configuration in the sync log names the setting
that’s wrong.
A device gets 401 / “the server refused this device’s key”. Look for
Authorization failed in the log. chain not allowed: <id> means the
server is private and the chain isn’t on
the list; this client ID is blocked means it’s in BLOCKED_CLIENT_IDS.
A token that’s out of date can also mean the device’s clock is off by more
than a day.
401 {"error":"login_required"}. Company sign-in
is on and the chain isn’t signed in (or its session ended, or the user was
revoked). Compass asks to sign in. If the sign-in page never opens, check
the log for Sign-in: identity provider still unreachable.
Pairing says the code is wrong every time. The two devices reach the
server by different names (an IP address and a host name, or a Tailscale
name). Use the same server URL on both, or set COMPASS_SYNC_PUBLIC_HOST.
Behind your own proxy, make sure it passes the Host header through.
Pairing hits “too many attempts” (429). Behind a reverse proxy
without COMPASS_SYNC_TRUSTED_PROXIES, every device has the proxy’s
address and shares one limit (10 joins per 10 minutes). Set it to the
proxy’s address.
Changes take minutes to show up on other devices. The change
notification stream (/v2/compass/events) isn’t getting through: a proxy
is buffering it or closing it. Turn buffering off and keep idle timeouts
above 30 seconds (see your own reverse proxy).
curl -i https://sync.example.com/v2/compass/events should get the
server’s own 401 (invalid sync token) at once, which shows the path
reaches it. Devices also fall back to syncing every 15 minutes, on focus and on wake.