En

Backup and recovery#

This article describes backup contents and recovery preparation for a Docker distribution with built-in MariaDB or PostgreSQL. Before performing operations, the administrator needs the procedure for the installed version and database engine. Agree on external database procedures with its administrator.

Backup contents#

A complete installation backup includes:

  • The main and archive MariaDB databases, or the entire PostgreSQL database including its main and archive schemas.
  • .env, docker-compose.yml, and the docker-compose.override.yml in use.
  • backend/config, nginx configuration, and certificates.
  • Storage data from the orchestrator-storage volume.
  • Vault data, .vault_keys.json, and vault/config/vault.hcl if Vault is used.

A database dump does not contain the other files and volumes listed above. Preserve the original ORCHESTRATOR_ENCRYPTION_KEY and Vault unseal keys; otherwise restored secrets may be inaccessible.

Creating and verifying a backup#

Before stopping services, obtain the database backup and restore procedure for your version and database engine from Sherpa technical support. It provides database commands. Separately prepare and test procedures for copying and restoring configuration, certificates, Storage, and Vault according to the mounted volumes. The installation backup is not complete until recovery of all components has been verified.

  1. Agree on a maintenance window, check free space, and select a protected backup directory.
  2. Stop the backend, WebSocket, nginx, and external integrations that write data. Keep the selected database container running.
  3. Create a dump for the selected database engine using the supplied procedure and a time-consistent copy of files and volumes. Adapt commands for nonstandard database names before running them.
  4. Check each command's exit status, ensure the dump is nonempty, and verify checksums. Transfer a copy off the server while preserving access restrictions.
  5. Test recovery using a separate database instance and separate volumes. A dump file alone does not prove that a backup is usable.

If no update or restore is planned, restart services after copying according to the supplied procedure for the selected database engine.

Do not restart writers between taking the dump and updating. Otherwise the backup will no longer match the installation state before the update.

Recovery and rollback#

Recovery replaces the current data in the target database. A verified dump and a separate fresh backup of the current state are required first. Keep the application and external writers stopped.

For rollback, first restore images and configuration compatible with the dump. Then start only the database and follow the engine-specific recovery section in the supplied procedure for your version and database engine. PostgreSQL recovery uses a newly created database to avoid retaining objects from newer migrations. Test MariaDB recovery only in an isolated instance and volume.

Do not delete production volumes with docker compose down -v. Start the backend only after restoring the database, files, and secrets; it may apply migrations on startup.

After startup, verify login, access to Processes and Storage, Licenses, secret retrieval, and a safe test workflow. Keep the original backup until the result is confirmed.