Development
Source layout, tests and releases.
Layout
Section titled “Layout”| Path | What it is |
|---|---|
src/main.cpp |
Command line (users, devices, migrate, import, sweep, migrate-to-vaults) and server start-up |
src/Config.* |
The SYNC_* environment variables |
src/SyncApi.* |
Every HTTP route, preconditions, events (EventHub), CORS |
src/Jwt.* |
Access token verification and the JWKS cache |
src/Storage.* |
The storage interfaces (UserRepository, DatabaseRepository) and openStorage |
src/UserStore.*, src/DatabaseStore.* |
The data directory backend (SQLite and files) |
src/Postgres.*, src/Pg*Repository.*, src/BlobStore.* |
The Postgres and S3 backend (SigV4 signing, migrations, sweep) |
src/Import.*, src/Migrate.* |
import and migrate-to-vaults |
test/ |
API tests and the shared account test vectors |
docs/ |
These docs, the OpenAPI description and the stateless design notes |
Building and testing
Section titled “Building and testing”cmake -S . -B build -DCMAKE_BUILD_TYPE=Debugcmake --build build && ctest --test-dir build --output-on-failuresync_server_testcovers the self-hosted API.sync_server_jwt_testandsync_server_jwt_only_testcover the account side inbothandjwtmode, andsync_server_jwt_no_internal_testbothmode withoutSYNC_INTERNAL_TOKEN, against the shared test vectors intest/vectors/test-vectors.json(a copy of OpenVireo’sdocs/plans/accounts/test-vectors.json).docs_coveragefails when a route registered insrc/SyncApi.cppis missing fromdocs/openapi.yaml, or an environment variable read insrc/Config.cppis missing fromdocs/configuration.md.
The API tests use the data directory, or Postgres and S3 when SYNC_DATABASE_URL and SYNC_S3_* are set. To run
them against both locally:
docker compose -f compose.cloud.yaml run --rm --build testThe docs in docs/ are Markdown, published on openvireo.com by the
site’s npm run docs:dev from a release tag. Keep links between pages relative (api.md#events) so they work
on GitHub and on the site. A user-visible change (a route, a variable, a command) belongs in the same pull
request as its docs.
Releasing
Section titled “Releasing”Push a version tag: git tag v1.2.3 && git push origin v1.2.3. .github/workflows/release.yml runs the API tests,
builds the image for linux/amd64 and linux/arm64, publishes it to GHCR as :1.2.3, :1.2, :1 and :latest
(a pre-release only as itself), and creates the GitHub release with the binaries: Linux from Dockerfile.static,
macOS and Windows from .github/workflows/binaries-native.yml. That workflow publishes nothing, so a branch can be
tried with gh workflow run binaries-native.yml --ref <branch>; it builds with vcpkg (packaging/vcpkg), runs the
tests, packs each binary and checks with .github/scripts/smoke-test.sh that it starts and verifies TLS
certificates.