> 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/concepts/configuration-management.md).

# How Configuration Works

## Overview

Your **configuration** is the set of environment-specific settings that make a deployment yours — domain, database connection, storage buckets, cache, SSO, AI features, and so on. Together with the metadata database, it is one of the two [restore-critical](/carto-self-hosted/operations/backup-and-restore/backups.md) elements of an installation.

How you manage that configuration depends on your [deployment method](/carto-self-hosted/planning/deployment-methods.md):

* **Helm** uses a **file-based** model — you own a set of YAML files and apply them with `helm upgrade`.
* **Kots** (Standard Orchestrated and Single VM) uses the **Admin Console** — a web UI that stores your configuration in the cluster and versions it for you.

Understanding which model applies to you determines where your configuration lives, how you change it, and how you track it over time.

## Configuration by deployment method

{% tabs %}
{% tab title="☸️ Kots (Admin Console)" %}
A Kots deployment is configured through the [Admin Console](/carto-self-hosted/operations/licensing-and-admin/kots-admin-console.md) — a web UI that lets you set everything without editing YAML by hand. Your configuration is stored **in the cluster**, not in files you keep.

* The **Config** tab groups all editable settings (Application, Database, Object Storage, Cache, Networking, SSO, AI Features). After editing, you **Save config** and **Deploy** to apply changes — see [Apply configuration changes](/carto-self-hosted/operations/upgrades/apply-configuration-changes.md) for the step-by-step.
* The **Version history** tab is your built-in change log: it lists every deployed version and lets you view the **diff** between them (config changes and image updates) and roll a configuration forward to a specific version.
* The **Custom Configuration** field is a free-form YAML escape hatch for advanced Helm values, deep-merged last. Use it **only** with CARTO Support guidance.

Manage Kots configuration through the Admin Console, and back it up for disaster recovery following CARTO's [Kots backup procedure](/carto-self-hosted/operations/backup-and-restore/backups.md#backup-configuration-kots) and Replicated's [snapshot-based backup and restore](https://docs.replicated.com/vendor/snapshots-overview).
{% endtab %}

{% tab title="🛞 Helm (customizations.yaml)" %}
A Helm deployment is configured through a **layered** set of three files:

| File                  | Provided by | Do you edit it? | Contains                                         |
| --------------------- | ----------- | --------------- | ------------------------------------------------ |
| `carto-values.yaml`   | CARTO       | **No**          | Default application settings for your release    |
| `carto-secrets.yaml`  | CARTO       | **No**          | Your license and private registry credentials    |
| `customizations.yaml` | **You**     | **Yes**         | Your overrides and environment-specific settings |

When you install or upgrade, Helm **merges** the three files, with the values in your `customizations.yaml` taking precedence. You only ever edit `customizations.yaml`; the two CARTO-provided files are replaced as-is when you move to a new release.

To apply a configuration change, edit `customizations.yaml` and re-deploy with `helm upgrade` (this is an [*apply changes*](/carto-self-hosted/getting-started/glossary.md) operation, not a version change). See [Apply configuration changes](/carto-self-hosted/operations/upgrades/apply-configuration-changes.md) for the step-by-step, and the [Advanced customizations](/carto-self-hosted/reference/advanced-helm-customizations.md) reference for available overrides.
{% endtab %}
{% endtabs %}

## Where your configuration lives

|                                | Helm                                | Kots                     |
| ------------------------------ | ----------------------------------- | ------------------------ |
| **Edited via**                 | `customizations.yaml` (text editor) | Admin Console UI         |
| **Stored in**                  | Files you keep                      | The cluster              |
| **Versioned by**               | You (e.g. Git)                      | Kots **Version history** |
| **Apply a change**             | `helm upgrade`                      | Save config → Deploy     |
| **Built-in change log / diff** | No — you provide it                 | Yes — Version history    |

The practical consequence: with Helm you are responsible for tracking and backing up your configuration files; with Kots, the Admin Console tracks deployed versions for you, and you back up and restore the configuration using the [documented Kots backup procedure](/carto-self-hosted/operations/backup-and-restore/backups.md#backup-configuration-kots) rather than maintaining files by hand.

## Manage configuration as code

Whichever method you use, treat configuration as a tracked, reviewable artifact rather than ad-hoc live edits. The full set of recommendations — version control, secrets handling, review before apply, and the upgrade lifecycle — is covered in [Manage configuration as code](/carto-self-hosted/best-practices/operations/operations-best-practices.md#manage-configuration-as-code).

## Next steps

* [Backups & Restore](/carto-self-hosted/operations/backup-and-restore/backups.md) — what to back up and how to restore your configuration
* [Operations best practices](/carto-self-hosted/best-practices/operations/operations-best-practices.md) — version control, secrets, and update cadence
* [Choosing a deployment method](/carto-self-hosted/planning/deployment-methods/choosing-a-deployment-method.md) — Helm vs Kots vs Single VM


---

# 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/concepts/configuration-management.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.