Backups and restore
Backing up and restoring your CARTO Self-Hosted deployment
Ensuring the safety and security of your CARTO Self-Hosted version is crucial. Regular backups of your external database and configuration files are essential to protect your data and settings from unexpected failures, data corruption, or system crashes.
The CARTO platform only requires the configuration files of an existing installation and the contents of the metadata database to be completely restored, so that's why it's highly recommended to use an external database for self-hosted deployments.
Operations terminology
Backup / Restore
Point-in-time snapshot of configuration and metadata database so you can rebuild an identical deployment (this page).
Update / Upgrade
Moving to a newer CARTO release. These two terms mean the same thing. See Update to a new version.
Key rotation
Replacing secrets and credentials without changing the CARTO version. See Rotating keys.
What to back up
A complete CARTO Self-Hosted backup consists of two things:
Configuration
The installation's configuration — the Kots config, or the Helm carto-values.yaml, carto-secrets.yaml, and customizations.yaml files.
Metadata database
The full contents of your external PostgreSQL metadata database — maps, workflows, connections, users, and organizations.
Object storage: we recommend including the assets / thumbnails bucket (map thumbnails, custom markers) in your backups, as those files can't be regenerated on demand. The temp / import bucket is ephemeral and does not need backing up. Your data warehouse is external and managed by you, outside the CARTO backup scope.
The procedure differs by deployment method. Follow the Kots or Helm section below.
Backup configuration (Kots)
This section only applies to deployments using Kots (Single VM or Orchestrated container deployment with Kots).
It's possible to obtain a backup of the Self-Hosted configuration with the following command:
Run a shell in your CARTO Self-Hosted installation:
Install Kots CLI:
And obtain the actual config:
Restore an existing backup
Restoring is a disruptive operation. It causes downtime and, if done incorrectly, can result in data loss. Contact support@carto.com and work with the CARTO Self-Hosted team before starting a restore.
The process of restoring a CARTO Self-Hosted backup involves reinstalling CARTO with the same settings as before and ensuring that the external database, where your data is stored, is still operational and accessible to the new installation. This way, you can recreate your CARTO environment in a state identical to when the backup was created.
To restore an existing backup, you'll just have to perform a new Self-Hosted deployment using your existing license and configure the new installation with the config saved in your last backup.
Please note that sensitive information such as the PostgreSQL and Valkey passwords, stored within backups, cannot be directly accessed or retrieved from the backup files.
Backup and restore (Helm)
This section only applies to advanced Orchestrated container deployments using Kubernetes and Helm.
For Helm-based deployments, your backup strategy should include:
Your
carto-values.yaml,carto-secrets.yaml, andcustomizations.yamlconfiguration files — store these in version control. Keepcarto-secrets.yamlin a private repository or secrets manager.The contents of your external metadata database — use your cloud provider's automated snapshot feature (Cloud SQL, RDS, Azure Database for PostgreSQL) or
pg_dumpfor self-managed PostgreSQL:
Restore an existing backup
Restoring is a disruptive operation. It causes downtime and, if done incorrectly, can result in data loss. Contact support@carto.com and work with the CARTO Self-Hosted team before starting a restore.
The process of restoring a CARTO Self-Hosted backup involves reinstalling CARTO with the same settings as before and ensuring that the external database, where your data is stored, is still operational and accessible to the new installation.
Restore the metadata database from your snapshot or
pg_dumpbackup:
Reinstall CARTO using your backed-up configuration files:
Post-restore verification
After restoring from a backup, confirm the deployment is healthy:
Last updated
Was this helpful?
