Installing and deploying
Build from source, run the Docker image, deploy to DigitalOcean, put HTTPS in front.
Release binary
Section titled “Release binary”Each release has the server as one binary that needs nothing installed, with Postgres and S3 support, for:
| Platform | Archive |
|---|---|
| Linux x64, arm64 (any distribution, statically linked) | openvireo-sync-server-VERSION-linux-x64.tar.gz, …-linux-arm64.tar.gz |
| macOS 13.3 or later, Apple silicon and Intel | openvireo-sync-server-VERSION-darwin-arm64.tar.gz, …-darwin-x64.tar.gz |
| Windows 10, 11, Server 2016 or later, x64 | openvireo-sync-server-VERSION-windows-x64.zip |
Each archive has a directory openvireo-sync-server-VERSION with the binary, the licence, the README and these
docs. SHA256SUMS on the release lists their checksums, and SHA256SUMS.asc is its signature with the OpenVireo
release key, the same one as the desktop app’s releases: fingerprint
FE27 78BF 0747 05E0 994B BAF9 FEBA 3556 2DE1 04CB. Import it once, then gpg --verify SHA256SUMS.asc SHA256SUMS
must say “Good signature” with that primary key fingerprint (see
Verifying Signatures):
curl -sSL https://openvireo.com/openvireo-release.asc | gpg --import# or: gpg --keyserver hkps://keys.openpgp.org --recv-keys FE2778BF074705E0994BBAF9FEBA35562DE104CBFor an always-on server, Linux (with the systemd unit
below) or Docker is the best supported; on macOS and Windows the binary is as good for a server that
runs while you are logged in, for trying things out and for the users and devices commands.
v=VERSION a=x64 # VERSION: the release without the v, e.g. 0.2.0; a: x64 or arm64curl -LO "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v/openvireo-sync-server-$v-linux-$a.tar.gz"curl -LO "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v/SHA256SUMS"curl -LO "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v/SHA256SUMS.asc"gpg --verify SHA256SUMS.asc SHA256SUMSsha256sum --ignore-missing -c SHA256SUMStar -xzf "openvireo-sync-server-$v-linux-$a.tar.gz" && cd "openvireo-sync-server-$v"sudo install openvireo-sync-server /usr/local/bin/The archive also has a systemd unit, openvireo-sync-server.service, which runs the server as the user
openvireo-sync with its data in /var/lib/openvireo-sync-server and reads settings from
/etc/openvireo-sync-server.env:
sudo useradd --system --home-dir /var/lib/openvireo-sync-server --shell /usr/sbin/nologin openvireo-syncsudo install -m 0644 openvireo-sync-server.service /etc/systemd/system/echo SYNC_BEHIND_PROXY=1 | sudo tee /etc/openvireo-sync-server.env # see Configurationsudo systemctl enable --now openvireo-sync-serversudo -u openvireo-sync env SYNC_DATA_DIR=/var/lib/openvireo-sync-server openvireo-sync-server users add alice laptopFor HTTPS connections (the account server’s JWKS, S3) it uses the distribution’s CA certificates in
/etc/ssl (the ca-certificates package). It’s built by Dockerfile.static: docker build -f Dockerfile.static -o dist .
v=VERSION a=arm64 # a: arm64 (Apple silicon) or x64 (Intel)curl -LO "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v/openvireo-sync-server-$v-darwin-$a.tar.gz"curl -LO "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v/SHA256SUMS"curl -LO "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v/SHA256SUMS.asc"gpg --verify SHA256SUMS.asc SHA256SUMS # gpg from GPG Suite or brew install gnupgshasum -a 256 --ignore-missing -c SHA256SUMStar -xzf "openvireo-sync-server-$v-darwin-$a.tar.gz" && cd "openvireo-sync-server-$v"./openvireo-sync-server users add alice laptop./openvireo-sync-server # http://127.0.0.1:8787, data in ./dataThe binary is signed with OpenVireo’s Developer ID (team DP5U2UP42V) and notarized by Apple, so it runs even
when downloaded with a browser. A bare executable can’t carry its notarization ticket, so macOS checks it online
the first time. It uses only libraries that are part of macOS. To check the signature by hand:
codesign --verify --strict --verbose=2 openvireo-sync-server # valid on disk, satisfies its Designated Requirementcodesign -dv openvireo-sync-server 2>&1 | grep TeamIdentifier # TeamIdentifier=DP5U2UP42Vspctl --assess --type install -vv openvireo-sync-server # accepted, source=Notarized Developer IDFor HTTPS connections it trusts the CA certificates in /etc/ssl/cert.pem, the bundle macOS ships and updates
with the system. Certificates you added to the Keychain are not used: for a private CA (say, of your own account
server) set SSL_CERT_FILE to a PEM file with that CA and, if needed, the public ones (e.g. a copy of
/etc/ssl/cert.pem with your CA appended). To keep it running, use a launchd job (a LaunchAgent or LaunchDaemon
with SYNC_DATA_DIR in its EnvironmentVariables), or Docker.
Windows
Section titled “Windows”In PowerShell:
$v = "VERSION"$base = "https://github.com/OpenVireo/openvireo-sync-server/releases/download/v$v"Invoke-WebRequest "$base/openvireo-sync-server-$v-windows-x64.zip" -OutFile "openvireo-sync-server-$v-windows-x64.zip"Invoke-WebRequest "$base/SHA256SUMS" -OutFile SHA256SUMSInvoke-WebRequest "$base/SHA256SUMS.asc" -OutFile SHA256SUMS.ascgpg --verify SHA256SUMS.asc SHA256SUMS # gpg from Gpg4win(Get-FileHash "openvireo-sync-server-$v-windows-x64.zip").Hash # compare with its line in SHA256SUMSExpand-Archive "openvireo-sync-server-$v-windows-x64.zip" . ; cd "openvireo-sync-server-$v".\openvireo-sync-server.exe users add alice laptop.\openvireo-sync-server.exe # http://127.0.0.1:8787, data in .\dataThe binary is signed with Azure Artifact Signing, the same publisher as the OpenVireo desktop app’s installers,
so SmartScreen knows its publisher. To check the signature by hand (Status must be Valid):
Get-AuthenticodeSignature .\openvireo-sync-server.exe | Format-List Status, SignerCertificate, TimeStamperCertificateWindows Firewall asks for permission only if you make it listen on the network
(SYNC_HOST). It needs no runtime or DLLs beyond Windows itself.
Windows has no file modes: the files in the data directory inherit the directory’s access control list, so keep
SYNC_DATA_DIR somewhere only you or the server’s account can read, such as a folder in your user profile. For
HTTPS connections it trusts the certificates in Windows’ Trusted Root Certification Authorities store; add a
private CA there (Windows ignores SSL_CERT_FILE). Windows installs some public roots only when a Windows
program first needs them, so if a fetch fails with Invalid certificate for a public server, opening its URL
once in Edge installs the missing root.
It’s a console program, not a Windows service, so sc.exe create can’t run it. To keep it running without a
logged-in user, wrap it with a service wrapper such as WinSW or
NSSM and set SYNC_DATA_DIR there, or run it in Docker or WSL.
All platforms
Section titled “All platforms”The binary ignores the system’s openssl.cnf, which belongs to another OpenSSL (the distribution’s, macOS’s
LibreSSL); set OPENSSL_CONF to use one anyway. The macOS and Windows binaries are built and signed by
.github/workflows/binaries-native.yml (see .github/RELEASE-SIGNING.md); see From source to build one yourself.
From source
Section titled “From source”The server is C++17 on Drogon, with SQLite for the default storage.
brew install drogon sqlite # or: apt install libdrogon-dev libsqlite3-dev, vcpkg install drogon sqlite3, …cmake -S . -B build -DCMAKE_BUILD_TYPE=Releasecmake --build build./build/openvireo-sync-server # http://127.0.0.1:8787, data in ./dataPostgres and S3 support (see Storage) needs Drogon built with PostgreSQL
(-DBUILD_POSTGRESQL=ON), which Homebrew’s and most distributions’ packages are not. CMake turns it on
when it finds such a Drogon; -DSYNC_SERVER_WITH_CLOUD=ON makes it required. The Docker image always has it.
cmake --install build installs the single binary, openvireo-sync-server. It has no other files.
-DSYNC_SERVER_PORTABLE=ON makes it ignore the system’s openssl.cnf unless OPENSSL_CONF is set, as the
release binaries do.
With vcpkg (macOS and Windows)
Section titled “With vcpkg (macOS and Windows)”The release binaries for macOS and Windows link static libraries from vcpkg: the manifest
in packaging/vcpkg pins the versions (Drogon with PostgreSQL, OpenSSL, libpq, SQLite) and has triplets for
release-only static builds. You need CMake, a C++17 compiler (Xcode’s command line tools, or Visual Studio 2022
or later with Desktop development with C++), Git, Python 3.10 or later (vcpkg builds libpq with Meson) and a
clone of vcpkg:
git clone https://github.com/microsoft/vcpkg && ./vcpkg/bootstrap-vcpkg.sh # bootstrap-vcpkg.bat on Windowsexport VCPKG_ROOT=$PWD/vcpkgOn macOS (arm64-osx-release-static on Apple silicon, x64-osx-release-static on Intel):
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" \ -DVCPKG_MANIFEST_DIR="$PWD/packaging/vcpkg" -DVCPKG_TARGET_TRIPLET=arm64-osx-release-static \ -DSYNC_SERVER_WITH_CLOUD=ON -DSYNC_SERVER_PORTABLE=ON -DCMAKE_OSX_DEPLOYMENT_TARGET=13.3 \ "-DCMAKE_IGNORE_PREFIX_PATH=/opt/homebrew;/usr/local"cmake --build build && ctest --test-dir buildCMAKE_IGNORE_PREFIX_PATH keeps Homebrew’s libraries out of the binary. On Windows, in PowerShell:
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" ` -DVCPKG_MANIFEST_DIR="$PWD/packaging/vcpkg" -DVCPKG_TARGET_TRIPLET=x64-windows-release-static ` -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded -DSYNC_SERVER_WITH_CLOUD=ON -DSYNC_SERVER_PORTABLE=ONcmake --build build --config Release; ctest --test-dir build -C ReleaseThe first configure builds the libraries, which takes a while; vcpkg caches them for the next. The binary is
build/openvireo-sync-server (on Windows build\Release\openvireo-sync-server.exe).
Docker
Section titled “Docker”Released images for linux/amd64 and linux/arm64 are on GHCR:
docker run -d --name openvireo-sync -p 127.0.0.1:8787:8787 -v openvireo-sync:/data \ -e SYNC_BEHIND_PROXY=1 ghcr.io/openvireo/openvireo-sync-server:1docker exec openvireo-sync openvireo-sync-server users add alice laptopTags: :latest, :1, :1.2, :1.2.3 (a pre-release such as 1.3.0-rc.1 gets only its own tag). The image
runs as an unprivileged user (uid 10001), listens on 0.0.0.0:8787 and keeps the data directory in /data; a
bind-mounted directory must be writable by that uid. Publish the port on 127.0.0.1 only and put HTTPS in
front of it (see below); SYNC_BEHIND_PROXY=1 says you did.
To build from this repository instead:
docker compose up -d --build # data directory in a volume, on 127.0.0.1:8787docker compose run --rm sync-server users add alice laptopSYNC_HOST_PORT=18787 publishes on another port.
compose.cloud.yaml runs the stateless setup locally: Postgres, an S3 gateway standing in for Spaces, two
server instances and nginx in front of them:
docker compose -f compose.cloud.yaml up -d --builddocker compose -f compose.cloud.yaml run --rm migrate users add alice laptopdocker compose -f compose.cloud.yaml run --rm --build test # the API tests against Postgres and the bucketconfig/deploy.yml deploys the stateless setup with Kamal to a Docker host,
with a managed Postgres database and a Spaces bucket. kamal-proxy terminates HTTPS. Create the bucket and a
Spaces access key first, copy .kamal/secrets.example to .kamal/secrets (not in git) and fill it in, then:
kamal setup # first timekamal deploy # every time afterAdd users with kamal sync users add alice laptop, or from any machine with the same SYNC_* settings.
DigitalOcean App Platform
Section titled “DigitalOcean App Platform”App Platform can run the stateless setup too, with a managed Postgres database and a Spaces bucket. Save
the spec below as app.yaml, create the bucket and a Spaces access key, fill in the placeholders, set
cluster_name to your managed Postgres cluster (or remove production and cluster_name for a
development database), then:
doctl apps create --spec app.yamlname: openvireo-syncregion: nyc
services: - name: sync-server # Built from the Dockerfile on each deploy. To deploy a prebuilt image instead, replace github, # source_dir and dockerfile_path with: # image: # registry_type: GHCR # registry: <owner> # repository: openvireo-sync-server # tag: latest github: repo: <owner>/openvireo-sync-server branch: main deploy_on_push: true dockerfile_path: Dockerfile http_port: 8787 instance_count: 2 instance_size_slug: apps-s-1vcpu-1gb health_check: http_path: /api/v1/health envs: - key: SYNC_DATABASE_URL scope: RUN_TIME value: ${db.DATABASE_URL} # App Platform terminates TLS in front of the instances - key: SYNC_BEHIND_PROXY value: "1" - key: SYNC_S3_ENDPOINT value: https://nyc3.digitaloceanspaces.com - key: SYNC_S3_REGION value: nyc3 - key: SYNC_S3_BUCKET value: <bucket name> - key: SYNC_S3_ACCESS_KEY type: SECRET value: <spaces access key> - key: SYNC_S3_SECRET_KEY type: SECRET value: <spaces secret key>
databases: - name: db engine: PG version: "17" production: true cluster_name: <postgres cluster name>App Platform terminates HTTPS. The instances apply the schema when they start, under a lock, so no
pre-deploy job is needed. Add users from the app’s console (openvireo-sync-server users add alice laptop)
or from any machine with the same SYNC_* settings.
HTTPS and reverse proxies
Section titled “HTTPS and reverse proxies”The access token travels in the Authorization header, so OpenVireo’s apps and the SDK require HTTPS: they
refuse a plain http:// server unless it’s on the same computer (localhost, *.localhost, 127.0.0.0/8,
[::1]). A server on your local network needs HTTPS too. Keep the server on 127.0.0.1 and put a TLS-terminating reverse proxy (Caddy, nginx, …) in front of it. For
example, with Caddy:
sync.example.com { reverse_proxy 127.0.0.1:8787}With nginx, turn off buffering for the events stream and allow long-lived requests:
location / { proxy_pass http://127.0.0.1:8787; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_buffering off; # the server also sends X-Accel-Buffering: no proxy_read_timeout 1h; # events streams stay open; the server pings every 25 seconds client_max_body_size 50m; # at least SYNC_MAX_DB_BYTES}Things to keep in mind behind a proxy:
- The server warns when it listens on a non-loopback address;
SYNC_BEHIND_PROXY=1silences that once TLS is terminated in front of it. - OpenVireo does not follow redirects, so the token is never forwarded to another host. Enter the final
https://URL. - The pairing rate limit is per client address, and behind a proxy every client has the proxy’s address (see Pairing).
- If web apps call the server (see CORS), let the proxy pass
OPTIONSrequests through rather than answering them itself.