Operations and upgrades

Operate the app, API, execution services and datastores as one release set. Keep the deployment configuration and license details with your operational runbook.

Backups

Back up the database, blob/file storage, deployment configuration and secrets. A database-only backup cannot restore files stored separately. Protect backups according to the sensitivity of the source data, credentials and reversible token vaults they contain.

Preserve CRYPT_SECRET: it is used for stored credentials and deterministic masking key derivation. Replacing it during an upgrade can make credentials unreadable and change masking relationships. Preserve token and chat secrets as well unless you are performing a planned rotation with understood consequences.

Test restoration in an isolated environment. Confirm assets, scenario files, masking consistency and authentication configuration are usable before relying on the backup.

Upgrade

1. Review the supplied release notes and compatibility requirements.
2. Record the running release and configuration, and take a verified backup.
3. Schedule a window appropriate for active jobs and database migrations.
4. Set the intended release version in the deployment environment and follow the bundle's image-pull and startup instructions.
5. Inspect the initializer and service logs, then verify the workflows below.

Do not assume downgrading an image reverses a database migration. Use the release's rollback procedure and your database/storage restore plan when needed.

Know which build you are running

GET /health on the API reports version, gitSha and builtAt. The version is the release number and moves only when one is cut; gitSha is the commit the running image was built from, which is what distinguishes two deployments carrying the same version. Record it in step 2 above, and read it again after the upgrade to confirm the new image is actually the one serving traffic.

A gitSha of unknown means the image was built without that provenance - a local or third-party build, or one from before the images carried it. It is not a fault; it just means the version number is all you have to go on.

This is also the answer to "does my deployment have the route the documentation describes". The guides describe the current product, which can be ahead of both a self-hosted installation and the hosted service; the API reference your own installation serves is what it actually offers.

Verify after a change

Check HTTPS and sign-in, a read of existing assets, small generation, scenario execution, file upload/download and one representative integration. For masked workflows, compare a known test sample and review the masking report. Confirm failed checks are visible rather than treating an empty result as success.

Monitor disk and blob capacity, database health, worker availability, job failures and license state. A stalled queue and a failed scenario are different problems; inspect both the execution service and the run record.

Network and certificates

Targets must be reachable from the component executing the request. Hosted workers do not share your laptop's localhost. For corporate certificate authorities, use the trust configuration documented by your deployment bundle; do not disable TLS verification as a routine fix.

For authentication failures, use Self-hosted authentication. For execution failures, see Common errors.