Configuration & Vault

An instance is shaped by three things: static configuration read at startup, the vault that holds secrets and variables, and a declarative description of the instance's content that can be reconciled against the live database (config-as-code). This page explains how they fit together. Administrator how-tos for the vault are in Vault.

Configuration layers

Configuration is resolved from the outside in. Later layers override earlier ones for the fields they set.

1. Built-in defaults shipped with the server.
2. Instance configuration files, provided by the deploying partner and mounted into the container.
3. Environment overrides, for values that differ per deployment or must not sit in a file.
4. Vault overrides, for a small allow-list of fields that may be changed at runtime without a redeploy.

Every layer is validated against a configuration schema when the server starts. A missing required value or a wrongly typed one stops the process with a clear message rather than starting in a half-configured state.

What is configured

Category	Examples
Application	The public address of the web app, database connection, e-mail delivery through the mail plugin, seeding options.
Authentication	Session and refresh token policy, API key policy, password reset policy.
Microsoft Entra ID	The tenant and application registration used for sign-in, and the directory synchronisation settings and mapping.
Encryption	The keys that protect vault secrets and device pairing payloads.
Platform behaviour	Schedule rules and other product-level settings.
Integrations	Heartbeat and registration of the instance with the platform, external tracking of instance health.

Feature availability on the web app side (analytics, EHR, AI assistant) is configured on the web app deployment; see Deploying an Instance.

Runtime overrides

A few behavioural fields are marked overridable in the schema. For those, a vault entry with the field's key changes the effective value immediately, without restarting the server. This is how a feature is rolled from dry-run to enforcing while watching the logs. Overrides are:

• Opt-in per field. Only fields the schema marks as overridable can be changed this way, whatever a vault entry is named.
• Typed. A value that cannot be parsed as the declared type is ignored and logged; a typo cannot switch behaviour on.
• Logged. Each change is recorded old to new, with secret values masked.
• Non-critical only. Settings that establish trust, such as the identity provider tenant or token signing material, are never overridable.

Vault

The vault is an encrypted store inside the instance database for values that configuration, plugins, clinical sources and workflows need but that should not appear in plain text anywhere.

Entry kind	Stored as	Typical use
Secret	Encrypted at rest, masked in logs	API keys of external systems, SMTP passwords, FHIR bearer tokens.
Variable	Plain text	Base URLs, identifiers, behaviour flags.
File	A reference to a file mounted into the server by the operator	Credentials delivered as files, such as long-lived tokens.

Entries are identified by a key chosen when they are created. Values of secrets are never returned by the API after creation; they can only be replaced.

References

Rather than copying a value into a configuration, you reference the entry by key, and the server substitutes the value at the moment it is used:

Form	Resolves to
$secret:<key>	The decrypted value of a secret entry.
$var:<key>	The value of a variable entry.
$file:<path>	The contents of a file the operator has explicitly allowed the server to read.

References are accepted in plugin instance settings, clinical source connection settings, workflow node inputs, plugin host-API key bindings and the allow-listed configuration overrides. Because resolution happens at use time, rotating a credential is a single update of the vault entry; nothing that references it changes.

Config-as-code

Beyond runtime settings, an instance has content that must exist before it is useful: the bootstrap administrator, and in growing scope the default folders, engines, plugins and workflows. The server can reconcile that content from a versioned manifest:

Command	Effect
validate	Checks the manifest against its schema without touching the instance.
sync	Reads the live state of the managed sections from the instance.
plan	Shows the differences between the manifest and the live state.
apply	Applies the differences, recording what was applied so that the next plan reports only real drift.

The reconciliation is ownership-aware: it manages only what it created and never touches rows an administrator authored by hand, and it never rewrites credentials. Deploying partners run it as part of installation and upgrades; see Deploying an Instance and the CLI.