Skip to content
OpenVireoDeveloper
GitHub

Development

Source layout, tests and releases.

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
Terminal window
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build && ctest --test-dir build --output-on-failure
  • sync_server_test covers the self-hosted API.
  • sync_server_jwt_test and sync_server_jwt_only_test cover the account side in both and jwt mode, and sync_server_jwt_no_internal_test both mode without SYNC_INTERNAL_TOKEN, against the shared test vectors in test/vectors/test-vectors.json (a copy of OpenVireo’s docs/plans/accounts/test-vectors.json).
  • docs_coverage fails when a route registered in src/SyncApi.cpp is missing from docs/openapi.yaml, or an environment variable read in src/Config.cpp is missing from docs/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:

Terminal window
docker compose -f compose.cloud.yaml run --rm --build test

The 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.

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.