Backup and restore in Docker

In Pentaho Data Catalog deployments running on Docker Compose, administrators can configure and manage backups to protect critical application data and search metadata. The backup and restore framework supports business continuity by enabling the recovery of Data Catalog components, such as PostgreSQL and OpenSearch.

In PDC 11.0, MongoDB is replaced by FerretDB. Because FerretDB uses PostgreSQL as its underlying database in this deployment architecture, the PostgreSQL backup also includes FerretDB-backed application data.

Docker backup and restore operations support the following backup modes:

• Automated scheduled backups through Ofelia cron jobs.
• Manual on-demand backups through the pdc.sh script.

Backup retention is configured separately for PostgreSQL and OpenSearch. By default, backups are retained for 15 days. Older backups are removed automatically based on the configured retention period.

This section includes detailed procedures to:

• Configure backups in Docker
• Run a backup in Docker
• Verify backups in Docker
• Restore data from backup in Docker

Backup and restore operations must be performed by administrators with access to the Docker host, the Data Catalog Docker Compose deployment directory, and the pdc.sh script.

The Docker backup and restore process covers PostgreSQL and OpenSearch only. Back up deployment configuration files, host-level files, certificates, licenses, and any other customer-managed resources separately according to your organization’s backup and disaster recovery policies.

Configure backups in Docker

In Data Catalog Docker Compose deployments, backup schedule and retention settings are controlled by default environment variables in the vendor/.env.default file. By default, PostgreSQL and OpenSearch backups run daily, and backup files are retained for 15 days. Older backups are removed automatically based on the configured retention period.

Configure backup schedule and retention

You can also configure how often PostgreSQL and OpenSearch backups run and how long backup files are retained on the Docker host by updating environment variables from the conf/.env file. PostgreSQL and OpenSearch use separate environment variables for schedule and retention.

The following table describes the backup configuration variables.

Service	Environment variable	Default or example value	Description
PostgreSQL	PG_BACKUP_PATH	/pgdump	Specifies the backup path inside the PostgreSQL container.
PostgreSQL	GLOBAL_PG_BACKUP_DAYS	15	Specifies the number of days to retain PostgreSQL backups.
PostgreSQL	PDC_CRON_UM_POSTGRESQL_BACKUP_SCHEDULE	@daily	Specifies the PostgreSQL backup schedule.
OpenSearch	PDC_OPENSEARCH_BACKUP_DAYS	15	Specifies the number of days to retain OpenSearch backups.
OpenSearch	PDC_CRON_OPENSEARCH_SCHEDULE	@daily	Specifies the OpenSearch backup schedule.

Use one of the following schedule values, depending on how often you want backups to run.

Schedule value	Description
@daily or @midnight	Runs once a day at midnight.
@hourly	Runs once an hour.
@weekly	Runs once a week at midnight between Saturday and Sunday.
@monthly	Runs once a month at midnight on the first day of the month.
@yearly or @annually	Runs once a year at midnight on January 1.
@every <number>m	Runs at a custom interval, where <number> is the interval in minutes. For example, @every 720m runs every 12 hours.

Perform the following steps to configure the backup schedule and retention in Data Catalog:

Prerequisites

Before you configure backups, make sure the following requirements are met:

• You have administrator access to the Docker host.
• The Docker Compose environment is running.
• The Docker host has sufficient disk space to store backup files for the configured retention period.

Before changing backup configuration values, back up the existing conf/.env file so that you can restore the previous settings if needed.

Procedure

1. Log in to the Docker host where Data Catalog is installed.
2. Go to the Data Catalog Docker Compose deployment directory.

   cd /opt/pentaho/pdc-docker-deployment

3. Back up the existing conf/.env file.

   cp conf/.env conf/.env.bak-$(date +%Y%m%d-%H%M%S)

4. Open the conf/.env file in a text editor.

   vi conf/.env

5. To change the PostgreSQL backup settings, add or update the following variables:

   PG_BACKUP_PATH=/pgdump
   GLOBAL_PG_BACKUP_DAYS=15
   PDC_CRON_UM_POSTGRESQL_BACKUP_SCHEDULE=@daily

6. To change the OpenSearch backup settings, add or update the following variables:

   PDC_OPENSEARCH_BACKUP_DAYS=15
   PDC_CRON_OPENSEARCH_SCHEDULE=@daily

7. Save and close the conf/.env file.
8. Restart the Data Catalog Docker Compose services to apply the updated environment variables.

   ./pdc.sh stop
   ./pdc.sh up

9. Verify that the Data Catalog services are running.

   ./pdc.sh ps

Result

Backup schedule and retention settings are configured for PostgreSQL and OpenSearch. The scheduled backup jobs run according to the schedule values in the conf/.env file, and backup files are retained for the configured number of days.

The default retention period is 15 days for both PostgreSQL and OpenSearch. Increase the retention period only after confirming that the Docker host has sufficient storage for the additional backup files.

Run a backup in Docker

In Data Catalog Docker Compose deployments, PostgreSQL and OpenSearch scheduled backups run automatically once a day and are retained for 15 days by default. If you change the backup schedule or retention period in the conf/.env file, scheduled backups run according to the configured values. For more information, see Configure backup schedule and retention.

Run a manual backup

You can also run a manual backup to create an on-demand recovery point before planned maintenance, configuration changes, upgrades, host maintenance activities, restore tests, or other activities that might affect Data Catalog data.

Prerequisites

Before you run a manual backup, make sure the following requirements are met:

• You have administrator access to the Docker host.
• The Data Catalog Docker Compose environment is running.
• The Docker host has sufficient disk space for the backup files.

Procedure

1. Log in to the Docker host where Data Catalog is installed.
2. Go to the Data Catalog Docker Compose deployment directory.

   cd /opt/pentaho/pdc-docker-deployment

3. Verify that Data Catalog services are running.

   ./pdc.sh ps

4. Run a manual backup for PostgreSQL.

   ./pdc.sh manual-backup um-postgresql

5. Run a manual backup for OpenSearch.

   ./pdc.sh manual-backup opensearch

Result

Manual backups are created for PostgreSQL and OpenSearch. The backup files are stored in the corresponding Docker backup volumes and are available for restoration.

For a full recovery point, run the PostgreSQL and OpenSearch manual backups during the same maintenance window. This helps keep application data and search metadata aligned for restore operations.

Verify backups in Docker

After scheduled or manual backups run, verify that PostgreSQL and OpenSearch backup entries are present, backup files are stored in the expected Docker volumes, backup logs show no errors, and retention settings are applied as expected.

List available backups

Use the list-backups command to verify that PostgreSQL and OpenSearch backups are available for restore.

Prerequisites

Before you list available backups, make sure the following requirements are met:

• You have administrator access to the Docker host.
• PostgreSQL or OpenSearch backup jobs have run at least once.

Procedure

1. Log in to the Docker host where Data Catalog is installed.
2. Go to the Data Catalog Docker Compose deployment directory.

   cd /opt/pentaho/pdc-docker-deployment

3. List the available PostgreSQL backups.

   ./pdc.sh list-backups um-postgresql

4. List the available OpenSearch backups.

   ./pdc.sh list-backups opensearch

5. Review the command output and confirm that the expected backup entries are listed.

   For PostgreSQL, backup file names can use a format similar to the following example:

   basebackup_2026-05-12_00h00m.tar.gz

   For OpenSearch, snapshot names can use a format similar to the following example:

   snapshot_2026-05-12_00:00:00

Result

The available PostgreSQL and OpenSearch backups are listed. You can use the listed backup file or snapshot name when you restore data.

Restore data from backup in Docker

In Data Catalog Docker Compose deployments, administrators can restore PostgreSQL and OpenSearch data from previously created backups. Restoring data helps recover the Data Catalog environment after data loss, data corruption, host failure, or an unsuccessful configuration change.

• Restoring a backup can overwrite current service data. Before you restore PostgreSQL or OpenSearch data, stop all running Data Catalog services to prevent conflicts during the restore operation.
• For a full environment recovery, restore PostgreSQL and OpenSearch backups from the same backup window. Using backups from different times can cause differences between application data and search metadata.

Prerequisites

Before you restore data from a backup, make sure the following requirements are met:

• You have administrator access to the Docker host.
• The required PostgreSQL or OpenSearch backup is available in the corresponding Docker backup volume.
• You have stopped all running Data Catalog services before starting the restore operation.
• The Docker host has sufficient disk space for the restore operation.

Perform the following steps before you restore PostgreSQL or OpenSearch data:

Procedure

1. Log in to the Docker host where Data Catalog is installed.
2. Go to the Data Catalog Docker Compose deployment directory.

   cd /opt/pentaho/pdc-docker-deployment

3. List the available PostgreSQL backups.

   ./pdc.sh list-backups um-postgresql

4. List the available OpenSearch backups.

   ./pdc.sh list-backups opensearch

5. Note the backup file name or snapshot name that you want to restore.

   PostgreSQL backup file names can use a format similar to the following example:

   basebackup_2026-05-12_00h00m.tar.gz

   OpenSearch snapshot names can use a format similar to the following example:

   snapshot_2026-05-12_00:00:00

6. Stop all running Data Catalog services.

   ./pdc.sh stop

Result

Data Catalog services are stopped, and the environment is ready for restoration.

Restore PostgreSQL data

Restore PostgreSQL data when you need to recover Data Catalog application data and FerretDB-backed application data. In PDC 11.0, FerretDB uses PostgreSQL as its underlying database, so restoring PostgreSQL restores the FerretDB-backed data stored in PostgreSQL.

Procedure

1. From the Data Catalog Docker Compose deployment directory, restore the PostgreSQL backup.

   ./pdc.sh restore-backup um-postgresql <backup_file_name>

   Replace <backup_file_name> with the PostgreSQL backup file that you want to restore.

   Example:

   ./pdc.sh restore-backup um-postgresql basebackup_2026-05-12_00h00m.tar.gz

2. Wait for the restore command to complete.
3. Review the command output and confirm that the restore completed successfully.

Result

PostgreSQL data is restored from the selected backup file. After you start Data Catalog services, the restored application data is available to Data Catalog.

Restore OpenSearch data

Restore OpenSearch data when you need to recover search indexes and related search metadata used by Data Catalog search and discovery features.

Procedure

1. From the Data Catalog Docker Compose deployment directory, restore the OpenSearch snapshot.

   ./pdc.sh restore-backup opensearch <backup_file_name>

   Replace <backup_file_name> with the OpenSearch snapshot name that you want to restore.

   Example:

   ./pdc.sh restore-backup opensearch snapshot_2026-05-12_00:00:00

2. Wait for the restore command to complete.
3. Review the command output and confirm that the restore completed successfully.

Result

OpenSearch data is restored from the selected snapshot. After you start Data Catalog services, the restored search metadata is available to Data Catalog.

Start and verify PDC after restore

After you restore PostgreSQL or OpenSearch data, start Data Catalog services and verify that the restored environment is working as expected.

Procedure

1. Start Data Catalog services.

   ./pdc.sh up

2. Verify that the services are running.

   ./pdc.sh ps

3. Check the PostgreSQL service logs.

   ./pdc.sh logs um-postgresql

4. Check the OpenSearch service logs.

   ./pdc.sh logs opensearch

5. Log in to the Data Catalog user interface.
6. Verify that the expected catalog data is available.
7. Verify that search results and metadata views are available.
8. If the restored data is not visible in the Data Catalog user interface, restart the Data Catalog application.

   ./pdc.sh restart

9. Log in again and verify the restored data.

Result

Data Catalog services are running, and the restored PostgreSQL or OpenSearch data is available in the Data Catalog user interface.

Restore backups on another Docker host

You can restore backups on another Docker host when you need to recover Data Catalog after host failure or migrate a backed-up environment to a replacement host. Before you run the restore commands on the target host, copy the required backup files from the source host to the corresponding backup volume paths on the target host.

Restore backups on another Docker host only when the target host is prepared for the same PDC 11.0 Docker Compose deployment. Restoring backups to an incompatible deployment can cause restore failure or data inconsistency.

Prerequisites

Before you restore backups on another Docker host, make sure the following requirements are met:

• PDC 11.0 Docker Compose deployment is installed on the target host.
• You have administrator access to the source and target Docker hosts.
• The Data Catalog services on the target host are stopped.
• The required Docker backup volumes exist on the target host.
• The PostgreSQL and OpenSearch backup files that you want to restore are available on the source host.
• You can securely copy files from the source host to the target host.

Procedure

1. Log in to the target Docker host.
2. Go to the Data Catalog Docker Compose deployment directory.

   cd /opt/pentaho/pdc-docker-deployment

3. Stop all running Data Catalog services on the target host.

   ./pdc.sh stop

4. Verify that the PostgreSQL backup volume path exists on the target host.

   sudo ls -ld /var/lib/docker/volumes/pdc_um-postgresql-bkp_data/_data/

5. Verify that the OpenSearch snapshot volume path exists on the target host.

   sudo ls -ld /var/lib/docker/volumes/pdc_opensearch_snapshots/_data/

6. From the source host, copy PostgreSQL backup data to the target host.

   scp -r /var/lib/docker/volumes/pdc_um-postgresql-bkp_data/_data/* \
   user@<target-host>:/var/lib/docker/volumes/pdc_um-postgresql-bkp_data/_data/

7. From the source host, copy OpenSearch snapshot data to the target host.

   scp -r /var/lib/docker/volumes/pdc_opensearch_snapshots/_data/* \
   user@<target-host>:/var/lib/docker/volumes/pdc_opensearch_snapshots/_data/

8. Log in to the target Docker host.
9. Go to the Data Catalog Docker Compose deployment directory.

   cd /opt/pentaho/pdc-docker-deployment

10. List the PostgreSQL backups copied to the target host.

    ./pdc.sh list-backups um-postgresql

11. List the OpenSearch backups copied to the target host.

    ./pdc.sh list-backups opensearch

12. Restore PostgreSQL data.

    ./pdc.sh restore-backup um-postgresql <backup_file_name>

13. Restore OpenSearch data.

    ./pdc.sh restore-backup opensearch <backup_file_name>

14. Start Data Catalog services.

    ./pdc.sh up

15. Verify that the services are running.

    ./pdc.sh ps

16. Check the service logs.

    ./pdc.sh logs um-postgresql
    ./pdc.sh logs opensearch

17. Log in to the Data Catalog user interface and verify that the restored catalog data and search results are available.
18. If restored data is not visible in the Data Catalog user interface, restart the Data Catalog application.

    ./pdc.sh restart

Result

The PostgreSQL and OpenSearch backups are copied to the target Docker host and restored successfully. Data Catalog starts on the target host with the restored application data and search metadata.