Skip to content

Back up and restore the server

Use this guide to create a complete backup of a Docker server and restore the server with its matching data.

This guide applies only to Docker deployments.

Info

The exact backup and restore operations depend on your deployment configuration. Use the active storage mappings and the official Docker documentation to complete each step.

A recovery set contains the database backup, file storage, and deployment configuration captured from the same consistent state, called a recovery point. Restore the recorded images together with this matching recovery set into fresh targets.

Prepare the recovery set

Record versions and storage

  1. Record the exact versions and image tags for the application, supporting services, and PostgreSQL. Record each immutable image digest, which identifies the exact image needed to recreate the backed-up deployment.
  2. Record the PostgreSQL major version, service identifiers, deployment configuration, and active ports.
  3. Inspect the actual non-database mounts on every product and supporting-service container. Include named volumes, anonymous volumes that don't have user-assigned names, and bind mounts.
  4. Record each container target and its host target. Compose declarations alone may omit anonymous volumes created by image VOLUME declarations.
  5. Record any external stores, secret locations, integrations, jobs, proxy settings, and extra mounts that the deployment uses.
  6. Confirm that each anonymous volume belongs only to this deployment before adding it to the cleanup or recovery plan.

Use this compact inventory to identify the standard storage locations.

  • Workspace: /opt/cloudbeaver/workspace, including its configuration and .data directory.
  • Application certificates: /opt/cloudbeaver/conf/certificates/.
  • Trusted and custom data: /opt/cloudbeaver/workspace/.data/custom/.
  • Keys: /opt/cloudbeaver/conf/keys/.
  • Proxy configuration and Transport Layer Security (TLS) data inside the web-proxy container:
    • Default nginx: /etc/nginx/product-conf/ for configuration and /etc/nginx/ssl/ for TLS data.
    • With PROXY_TYPE=haproxy: /etc/haproxy/product-conf/ for configuration and /etc/haproxy/ssl/ for TLS data.
    • Compose volume keys: nginx_conf_data for configuration and nginx_ssl_data for TLS data with either proxy.

Info

For information on identifying the database and workspace data, see Server Database, Query Manager database configuration, and Workspace backup.

Info

For information on the reference deployment, see Deployment from Docker Compose.

Create the backup

Stop writers

  1. Stop the application, proxy, jobs, integrations, and every other service that can write server data.
  2. Keep PostgreSQL running and create a logical backup. Include the database contents, database-level objects, roles, memberships, ownership, and configured schema names with their original case.
  3. Stop PostgreSQL after the logical backup completes.

Capture data

  1. Back up the remaining file storage and deployment configuration at the same recovery point. Exclude PostgreSQL data storage from the file-volume backup.
  2. Include the workspace or project storage and all required non-database mounts.
  3. Include licenses, certificates, keys, proxy data, and external stores when the deployment uses them.
  4. Preserve file contents, ownership, permissions, and symbolic links.

Info

For information on backing up and restoring Docker volumes, see Back up, restore, or migrate data volumes.

Verify the recovery set

  1. Check the contents of every backup artifact.
  2. Create and verify checksums, which confirm that the backup artifacts haven't changed.
  3. Complete a restore inventory with each source, destination, recovery point, service identifier, and image digest.
  4. Store the complete recovery set together in protected storage.

Restore the server

Prepare isolated targets

Info

Use an isolated deployment to verify restored data and services without changing the current deployment or its storage. Separate ports and storage keep both deployments independent during verification.

  1. Stop every service that can write to the target deployment.
  2. Verify the recovery set against its checksums and restore inventory.
  3. Create a fresh, isolated Docker deployment with non-conflicting ports.
  4. Create fresh PostgreSQL and file-storage targets for the restored deployment.
  5. Keep the original deployment and its storage unchanged until you accept the restored server.
  6. Pin the application, supporting-service, and PostgreSQL images to their recorded immutable digests.

Info

For information on pinning images, see the Compose image reference.

Restore database and file storage

Restore PostgreSQL

  1. Start only the fresh PostgreSQL target.
  2. Connect to it with a database administrator account. Complete restoration requires database administrator privileges.

  3. Restore roles and memberships first. This creates the owners referenced by the database backup before PostgreSQL restores the database objects.

    Info

    A fresh PostgreSQL instance already contains its built-in administrator role. Restore that role's attributes and memberships without trying to create the role again.

  4. Restore or recreate the database with its recorded name and owner. Use the PostgreSQL restore tool that matches the logical backup format.

  5. Restore or confirm the configured schemas, tables, data, ownership, and grants.
  6. Verify that the database is ready. Then authenticate with the database account configured for the product services.

Restore file storage

  1. Keep the fresh PostgreSQL data storage separate. Don't copy old PostgreSQL files into it because PostgreSQL is restored from the logical backup.
  2. Create each fresh non-database storage target listed in the recovery inventory.
  3. Restore each archive into its matching volume, bind-mount path, or external target before product services attach.
  4. Verify checksums, ownership, permissions, and symbolic links.
  5. Configure named volumes and recovered anonymous volumes at their recorded container targets.
  6. Set volume.nocopy: true where image defaults could be copied into restored named volumes.
  7. Keep any recovery Compose configuration or override required for later Compose operations.
  8. When possible, capture stable business-data counts and representative project files before product startup. Use this baseline after startup, and track expected runtime and service metadata changes separately.

Start services

  1. Start the remaining supporting services and product services in dependency order. Wait for the database and each application service to become ready before continuing.
  2. Start the proxy. It may return a short temporary startup error, such as HTTP 502, while PostgreSQL and the application initialize.
  3. Retry readiness checks for the operational timeout defined for your deployment. Inspect service logs if readiness doesn't complete within that timeout.
  4. Keep the restored deployment isolated until verification finishes.

Verify the restored server

Run functional checks

Complete these checks manually:

  • Confirm the reported product version and the running image digests for the product, supporting services, and PostgreSQL.
  • Sign in with representative administrator and regular-user accounts.
  • Verify users, teams, memberships, permissions, and relevant settings.
  • Open representative saved connections and confirm that their saved credentials work without exposing them.
  • Verify Query Manager history from the recovery point.
  • Open representative projects and Structured Query Language (SQL) scripts.
  • Confirm the license status through the documented product interface.
  • Confirm that the endpoint responds over HTTPS and that the restored certificate matches the recovery inventory.
  • Manually confirm in a production-equivalent client that hostname and trust-chain validation pass.

Use structural checks as a fallback

Use structural checks when functional user interface checks are unavailable. They supplement the manual functional checks and don't replace them. Mark the functional checks as pending.

  1. Compare stable business data and representative records with the recovery inventory.
  2. Compare representative users, teams, memberships, permissions, settings, connection metadata, Query Manager history, and projects when applicable.
  3. Compare schema and table counts, roles, and ownership.
  4. Compare project files and SQL scripts with the pre-startup baseline, restored file inventory, and checksums.
  5. Check service health and startup logs for license recognition and the expected proxy and certificate state.

Startup can add expected runtime metadata, including Query Manager service records. Compare stable business data instead of requiring exact equality for runtime metadata tables.

Finish the recovery

Keep the verified recovery set and the original deployment until the restored server passes the required checks and is accepted. Retain the recovery set according to your retention policy.