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

Term	Meaning
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:

Element	What it is
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:

Orchestrated container deployment

kubectl kots get config -n <namespace> --decrypt

Single VM deployment

Restore an existing backup

Restoring is a disruptive operation. It causes downtime and, if done incorrectly, can result in data loss. Contact [e-mail] 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, and customizations.yaml configuration files — store these in version control. Keep carto-secrets.yaml in 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_dump for self-managed PostgreSQL:

pg_dump -h <db-host> -U <db-user> -d <db-name> -F c -f carto-metadata-$(date +%Y%m%d).dump

Restore an existing backup

Restoring is a disruptive operation. It causes downtime and, if done incorrectly, can result in data loss. Contact [e-mail] 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.

1. Restore the metadata database from your snapshot or pg_dump backup:

pg_restore -h <db-host> -U <db-user> -d <db-name> -F c carto-metadata-<date>.dump

1. Reinstall CARTO using your backed-up configuration files:

helm install carto carto/carto \
  --namespace <namespace> \
  -f carto-values.yaml \
  -f carto-secrets.yaml \
  -f customizations.yaml

Post-restore verification

After restoring from a backup, confirm the deployment is healthy:

• All pods are in Running or Completed state

• The CARTO application is reachable and you can log in

• Maps and connections created before the backup are present

• Data warehouse connections are healthy

• Object storage (blob buckets) is accessible and writable