> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-self-hosted/operations/backup-and-restore/backups.md).

# Backups and restore

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](/carto-self-hosted/operations/upgrades/updates.md). |
| **Key rotation**     | Replacing secrets and credentials without changing the CARTO version. See [Rotating keys](/carto-self-hosted/operations/upgrades/rotating-keys.md).     |

## 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](#backup-configuration-kots) or [Helm](#backup-and-restore-helm) section below.

## Backup configuration (Kots)

{% hint style="info" %}
This section only applies to deployments using **Kots** (Single VM or Orchestrated container deployment with Kots).
{% endhint %}

It's possible to obtain a backup of the Self-Hosted configuration with the following command:

{% tabs %}
{% tab title="Orchestrated container deployment" %}

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

{% endtab %}

{% tab title="Single VM deployment" %}
Run a shell in your CARTO Self-Hosted installation:

```bash
sudo ./carto shell
```

Install Kots CLI:

```bash
curl https://kots.io/install | sudo bash
```

And obtain the actual config:

```bash
kubectl kots get config -n kotsadm --decrypt
```

{% endtab %}
{% endtabs %}

### Restore an existing backup

{% hint style="warning" %}
**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.
{% endhint %}

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.

{% hint style="info" %}
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.
{% endhint %}

## Backup and restore (Helm)

{% hint style="info" %}
This section only applies to **advanced Orchestrated container deployments** using **Kubernetes** and **Helm**.
{% endhint %}

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:

```bash
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

{% hint style="warning" %}
**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.
{% endhint %}

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:

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

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

```bash
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


---

# 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.carto.com/carto-self-hosted/operations/backup-and-restore/backups.md?ask=<question>&goal=<endgoal>
```

`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.