> For the complete documentation index, see [llms.txt](https://docs.pentaho.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pentaho.com/pdc-admin/backup-and-restore/backup-and-restore-in-docker.md). # 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. {% hint style="warning" %} 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. {% endhint %} This section includes detailed procedures to: * [Configure backups in Docker](https://hv-eng.atlassian.net/wiki/spaces/PDC/pages/edit-v2/33983431193#Configure-backups-in-Docker) * [Run a backup in Docker](#run-a-backup-in-docker) * [Verify backups in Docker](#verify-backups-in-docker) * [Restore data from backup in Docker](#restore-data-from-backup-in-docker) {% hint style="info" %} 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. {% endhint %} {% hint style="info" %} 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. {% endhint %} ## 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.
ServiceEnvironment variableDefault or example valueDescription
PostgreSQLPG_BACKUP_PATH/pgdumpSpecifies the backup path inside the PostgreSQL container.
PostgreSQLGLOBAL_PG_BACKUP_DAYS15Specifies the number of days to retain PostgreSQL backups.
PostgreSQLPDC_CRON_UM_POSTGRESQL_BACKUP_SCHEDULE@dailySpecifies the PostgreSQL backup schedule.
OpenSearchPDC_OPENSEARCH_BACKUP_DAYS15Specifies the number of days to retain OpenSearch backups.
OpenSearchPDC_CRON_OPENSEARCH_SCHEDULE@dailySpecifies the OpenSearch backup schedule.
Use one of the following schedule values, depending on how often you want backups to run.
Schedule valueDescription
@daily or @midnightRuns once a day at midnight.
@hourlyRuns once an hour.
@weeklyRuns once a week at midnight between Saturday and Sunday.
@monthlyRuns once a month at midnight on the first day of the month.
@yearly or @annuallyRuns once a year at midnight on January 1.
@every <number>mRuns 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. {% hint style="info" %} Before changing backup configuration values, back up the existing `conf/.env` file so that you can restore the previous settings if needed. {% endhint %} **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. {% hint style="info" %} 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. {% endhint %} ## 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](#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. {% hint style="info" %} 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. {% endhint %} ## 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. {% hint style="info" %} * 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. {% endhint %} **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 ``` Replace `` 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 ``` Replace \ 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@:/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@:/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 ``` 13. Restore OpenSearch data. ``` ./pdc.sh restore-backup opensearch ``` 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pentaho.com/pdc-admin/backup-and-restore/backup-and-restore-in-docker.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.