Install with Docker
The recommended setup is two containers: the sync server, and
Caddy in front of it, which gets and renews an
HTTPS certificate by itself. The server image is
ghcr.io/compass-browser/compass-sync-server (for linux/amd64 and
linux/arm64):
| Tag | What it is |
|---|---|
latest |
The newest build of the main branch |
sha-<short commit> |
One specific build, if you want to pin a version |
Docker Compose with Caddy
Section titled “Docker Compose with Caddy”You need a Linux machine with Docker and the Compose plugin
(docker compose version prints a version), and a domain name. These
steps use sync.example.com: put your own name in its place.
-
Point the name at the machine. Create a DNS
Arecord (andAAAAfor IPv6) forsync.example.comwith the machine’s public address. -
Open ports 80 and 443 (TCP, and UDP 443 for HTTP/3) in the machine’s firewall and your provider’s. Caddy needs port 80 to get the certificate.
-
Download the two files into a new directory:
Terminal window mkdir compass-sync && cd compass-synccurl -fsSLO https://raw.githubusercontent.com/Compass-Browser/Compass/main/server/docker-compose.ymlcurl -fsSLO https://raw.githubusercontent.com/Compass-Browser/Compass/main/server/Caddyfile -
Set your domain in
Caddyfile:Terminal window sed -i 's/sync.example.com/sync.your-domain.org/' CaddyfileThe file is three lines of configuration; you can also edit it by hand.
-
Start it:
Terminal window docker compose up -ddocker compose logs -fCaddy fetches the certificate at the first request. Press Ctrl+C to stop following the logs; the containers keep running.
-
Check it from any machine:
Terminal window curl https://sync.example.com/healthzIt answers
ok.docker compose psshould show thesynccontainer ashealthyafter half a minute. -
Connect Compass. Turn on sync with the server URL
https://sync.example.com/v2(the address followed by/v2). Other devices join the chain as usual, by pairing or with the recovery code.
That’s all: the containers restart with the machine, the server backs its database up once a day into its volume, and Caddy renews the certificate.
What’s in the files
Section titled “What’s in the files”docker-compose.ymlruns the server (no port published: only Caddy reaches it), Caddy on ports 80 and 443, and three named volumes: the server’s data (sync-data, mounted at/data) and Caddy’s certificates. It puts both on a fixed internal network,172.30.240.0/24, and tells the server to believe Caddy’sX-Forwarded-Forfrom it (COMPASS_SYNC_TRUSTED_PROXIES), so per-address limits see the devices’ real addresses.Caddyfilesends everything for your domain to the server, with response buffering off for the long-lived change-notification stream.
Settings go in docker-compose.yml, under sync’s environment; the file
lists the common ones, commented out. After a change, run
docker compose up -d again. See Configuration
for all of them.
Just docker run
Section titled “Just docker run”Without Caddy, the server alone listens on port 8295 over plain HTTP. Use this behind a reverse proxy you already have, or on a private network:
docker run -d --name compass-sync --restart unless-stopped \ -p 127.0.0.1:8295:8295 -v compass-sync-data:/data \ ghcr.io/compass-browser/compass-sync-server:latest-p 127.0.0.1:8295:8295 keeps it reachable from this machine only; point
your proxy at http://127.0.0.1:8295. Settings are -e NAME=value
options. See Other setups for nginx, Traefik
and Tailscale.
- Make it friends only or require company sign-in.
- Read Operations for backups, upgrades and monitoring.