Deployment guide
Self-hosted and managed deployments, environments, regions, first deployment, updates, backups and release hygiene.
A Symorva community runs as a deployment the operator owns. This guide covers how to choose a deployment mode, how environments are separated, how a first deployment is brought up, and how updates are delivered safely. It reflects the practices of the reference deployment.
Deployment modes
deployment.mode takes one of two values.
self-hosted | managed | |
|---|---|---|
| Infrastructure | The operator's cloud account or servers | Run by the Symorva team for the operator |
| Data stores | Operator-owned and operated | Operator-owned, operated by the Symorva team |
| Secrets and signing identities | Held by the operator | Held in the operator's secret store; access agreed per engagement |
| Upgrades | Applied by the operator from versioned releases | Applied by the Symorva team on an agreed schedule |
| Shared services | Connected as configured | Connected as configured |
In both modes the community's data stays in the operator's environment, and the operator's domain, app identifiers and signing identities stay the operator's. A community can move between modes without changing its manifest's module configuration.
Regions
deployment.region names the region the operator's deployment runs in. It is a free-form identifier of 2 to 40 characters, so it can carry the naming scheme of whatever infrastructure the operator uses. Region placement of shared services for a community is agreed per engagement.
Environments
Run separate environments for development, staging and production. Environments never share data, credentials, infrastructure state or release records.
- Separate app identifiers. Each environment builds its own app variant — for example with a
.devor.stagingsuffix — so builds install side by side and cannot read each other's data. - Separate configuration. Each environment has its own generated runtime configuration, kept outside version control.
- Separate verification. Development environments may use fixed test verification codes; staging and production use real delivery.
First deployment
Validate the manifest
symorva validate && symorva plan --json > plan.jsonThe plan lists exactly which components to provision (plan.owned) and which shared services to connect (plan.shared).
Prepare configuration and secrets
Copy the example configuration contracts for each service and generate environment-specific values. Random passwords and service-to-service tokens are generated locally and never committed; existing values are never overwritten by the generator. Validate configuration before starting anything.
Initialise the databases
Load the published schema baseline into each empty business database with the explicit bootstrap command. Bootstrap refuses a database that already has data. Managed migrations then bring it to the current version.
Start the messaging core, then the services
The messaging core and the business services run as separate failure domains on a shared internal network. Start the messaging core first, then the community server and module services. Each service runs its migrations before it accepts traffic.
Check health
curl --fail https://community.orbit.example/healthz
curl --fail https://community.orbit.example/readyz/healthz reports that the process is alive; /readyz reports that its dependencies are reachable.
Build and sign the apps
Generate the client configuration for the environment, build each platform target in plan.clients, and sign with the operator's identities.
Updates
Symorva ships versioned releases of the foundation modules. A release contains service images and any schema migrations they need.
- Migrations run on start. Deploying a new image applies its migrations under a per-database lock before the service starts. If a migration fails, the new service does not start; with a rolling deployment, the previous release continues to serve.
- Migrations are safe to re-run. They add only what is missing, never overwrite rows an operator has edited, never modify an already released migration and never grant roles.
- No silent rollbacks onto newer schemas. A binary refuses to run against a schema newer than the one it was built for. Roll forward with a fix rather than pointing an old binary at a migrated database.
- Images are pinned. Third-party base images are locked by digest, and every release records which source revision produced which image. A source revision being on the main branch does not mean it is running; the release record says what is.
- Releases are deliberate. Deploying to a shared environment is an explicit action, not a side effect of merging code.
Backups and restore
Back up every data store on a schedule the operator sets, including the messaging-core stores and object storage. In the reference deployment, a restored database is checked against financial invariants before it is put back into service: ledger postings balance and are paired, orders and refunds are posted consistently, references resolve, and no account balance is negative. Restores that fail an invariant are not promoted.
Secrets and configuration
- Real secrets, certificates, signing files and private keys live only in the operator's secret store or in generated runtime directories excluded from version control.
- Example configuration files document every variable each service reads.
- Repositories are scanned for credentials with a pinned scanner; any reviewed exception is recorded by file hash with a classification and rationale, and any byte change to that file requires a new review.
Observability
Each deployment exports service metrics and logs to the operator's monitoring stack and alerts on readiness, migration failures and delivery backlogs such as webhook and push queues. Shared services report per-community usage to the metering service; see Metering & settlement.