# Deployment requirements

In order to run CARTO on your own infrastructure setup, the following requirements must be met at a minimum:

### Recommended Background

Before proceeding with the installation, it is recommended that the individual performing the setup is familiar with cloud environments, specifically [GCP](https://cloud.google.com/) (Google Cloud Platform), [AWS](https://aws.amazon.com/) (Amazon Web Services), or [Azure](https://azure.microsoft.com/) (Microsoft Azure). This prior experience ensures a smoother deployment process and a better understanding of the underlying infrastructure.

1. **Cloud Platform Proficiency:** Basic proficiency in the chosen cloud platform is recommended. This includes the ability to navigate the respective console, manage instances or clusters, and configure networking settings.
2. **Account Authorization:** Ensure that you have the necessary permissions and access rights within your cloud platform account. This typically involves appropriate role assignments.
3. **Resource Understanding:** A grasp of fundamental concepts such as virtual machines, Kubernetes, storage, and networking within your chosen cloud environment will enhance your ability to deploy and manage resources effectively.

Having a solid understanding of cloud services will empower you to navigate the deployment process with confidence.

### Hardware and Software requirements

The hardware and software requirements below must be met to ensure an optimal performance of the CARTO platform:

#### Single VM deployment

Operating System requirements:

* Ubuntu 22.04, Debian 11 or above

CPU, memory and disk requirements:

<table><thead><tr><th>Requirements</th><th width="248.560546875">AI Features disabled</th><th>AI Features enabled</th></tr></thead><tbody><tr><td>CPU (x86)</td><td>8</td><td>16</td></tr><tr><td>Memory</td><td>32 GB</td><td>64 GB</td></tr><tr><td>Disk size</td><td>60</td><td>60</td></tr></tbody></table>

#### Orchestrated deployment (Kubernetes)

* Kubernetes 1.29 or above
* [Helm ](https://helm.sh/docs/intro/install/)3.6.0 or above
* At least 3 nodes with 4x vCPUs and 16 GB of memory
* An isolated namespace in which CARTO resources could be deployed. In case you're deploying more than one CARTO instances, there should be a namespace per installation.
* **If you'll deploy using KOTS:** Persistent volumes configured in your cluster, as the Admin Console will store configuration changes in a persistent volume.

### External databases

CARTO requires two dedicated PostgreSQL databases to manage its metadata. The first database is required to store metadata for the platform, and the second one is only required when [enabling CARTO AI in your Self-Hosted deployment](https://docs.carto.com/carto-self-hosted/guides/guides-helm/configure-carto-ai-prerequisites-helm) (this one can be omitted if you don't plan to use AI in CARTO).

The metadata information stored in these databases is the following:

* Configuration of Maps: data sources, layers, tooltips, legends, etc.
* Configuration of Workflows.
* Configuration of Applications.
* Connection credentials to other data warehouses like BigQuery, Snowflake, PostgreSQL, Redshift, Databricks, or Oracle.
* Credentials to connect with AI providers.
* Other CARTO internal metadata

{% hint style="info" %}
The CARTO metadata PostgreSQL database is only used to store CARTO metadata. This database is not the database to be used with CARTO to store your geospatial data.
{% endhint %}

These databases must be maintained (in terms of updates, backups, high availability, ...) by you. Our recommendation is to use the managed service provided by your cloud provider:

* Google: [Cloud SQL for PostgreSQL](https://cloud.google.com/sql/postgresql).
* AWS: [Amazon RDS for PostgreSQL.](https://aws.amazon.com/rds/postgresql/)
* Azure: [Azure Database for PostgreSQL](https://azure.microsoft.com/en-us/products/postgresql).

{% hint style="warning" %}
**Azure PostgreSQL Flexible Server**:

* Make sure you add ownership over the carto database and all privileges over the schema.
* Extensions must be allowlisted before creation. Run `az postgres flexible-server parameter set --name azure.extensions --value "pgcrypto"` then create the extension as the admin user. See [Azure docs](https://go.microsoft.com/fwlink/?linkid=2301063).
  {% endhint %}

**The current PostgreSQL recommended version is 14 or above.** The minimum requirements for production are:

* 1 vCPU
* 2 GB of RAM memory
* 20 GB of SSD storage

#### Naming Recommendations for PostgreSQL Instances

When deploying the PostgreSQL instance for CARTO Self-Hosted, we recommend following these best practices to ensure consistency and to avoid common configuration errors:

1. **Instance Name (Cloud SQL / RDS / VM-based PostgreSQL)**
   * Use a nomenclature that includes the **environment**.
   * Example:

     ```
     carto-prod-instance
     carto-dev-instance
     ```
2. **Database and User Names**
   * Use `carto` for both the **database name** and the **database user**.
   * Recommended:

     ```
     Database: carto
     User:     carto
     ```

{% hint style="warning" %}
:warning: **Important Constraint** :warning:

**Do not use hyphens (`-`)** in database names or usernames due to PostgreSQL constraints.

* If needed, replace hyphens with underscores (`_`).
* *Example*:
  * Allowed: **carto\_prod\_user, carto** :white\_check\_mark:
  * Not valid: **carto-prod-user, carto-maps** :x:
    {% endhint %}

{% hint style="warning" %}
:warning: **PostgreSQL Password Constraint** :warning:

**Avoid URI-special characters** (`@`, `#`, `%`, `/`, `?`, `&`, `=`, `+`) in the PostgreSQL user password. These characters can cause connection failures in components that construct database connection URLs internally, particularly the **AI Proxy (LiteLLM)**.

* Use alphanumeric passwords with underscores (`_`) or dashes (`-`).
* *Example*:
  * Recommended: **MyS3cure\_Pass123** :white\_check\_mark:
  * Problematic: **p\@ss#word!** :x:
    {% endhint %}

### Network ingress requirements

CARTO might need to be accessible to other people in your company (or the internet if you desire it) who needs using it. In order to do that, you need to configure:

* A full domain/subdomain that will be pointing to the machine.
* (Optional) A TLS certificate for the domain/subdomain. If no TLS certificate is provided, a self-signed certificate will be generated. The TLS certificate private key can't be protected with a passphrase.
* Access to HTTPS port (443). HTTP port (80) is optional and is going to redirect to HTTPS.

{% hint style="danger" %}
A full domain is required. You cannot install CARTO in a domain path like <https://my.domain.com/carto>
{% endhint %}

{% hint style="info" %}
If you would like to use some advanced features of Analytics Toolbox like LDS or some Wokflows features like import/export, your domain should be publicly accessible from the internet
{% endhint %}

### Network egress requirements

The CARTO Self-Hosted deployment requires access to some external services. Some of them are required for the software to work, and others depend on the cloud and data warehouse you will run and connect CARTO to. Finally, there is a set of optional services that you will need to open in case you will use those services with CARTO. For these services, HTTP/HTTPS domains must be “accepted”.

**Required services:**

| Domain                    | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `auth.carto.com`          | Auth system at CARTO based on [Auth0](https://auth0.com)       |
| `*.self-hosted.carto.com` | Used to deliver new Self-Hosted releases                       |
| `docker.io`               | Needed for downloading the images to execute the Admin Console |

**Cloud/Data warehouse specific requirements:**

Depending on the cloud you are deploying and the data warehouse you are using, you will also need to open certain services to connect your data.

| Provider     | Domain(s)                                                                                                       | Description                                                                                                                              |
| ------------ | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Google Cloud | `bigquery.googleapis.com`, `oauth2.googleapis.com`, `bigquerydatatransfer.googleapis.com`, `www.googleapis.com` | Required for BigQuery and [CARTO Data Warehouse](https://docs.carto.com/carto-self-hosted/guides/guides/enable-the-carto-data-warehouse) |
| Google Cloud | `storage.googleapis.com`, `www.googleapis.com`                                                                  | Access to CARTO platform [buckets](https://docs.carto.com/carto-self-hosted/guides/guides/configure-your-own-buckets)                    |
| AWS          | `*.amazonaws.com`                                                                                               | Required for AWS S3 [buckets](https://docs.carto.com/carto-self-hosted/guides/guides/configure-your-own-buckets)                         |
| Azure        | `*.blob.core.windows.net`                                                                                       | Required for [Azure Blob storage](https://docs.carto.com/carto-self-hosted/guides/guides/configure-your-own-buckets)                     |
| Snowflake    | `*.snowflakecomputing.com`                                                                                      | Required for Snowflake connections                                                                                                       |
| Databricks   | `*.databricks.com`                                                                                              | Required for Databricks connections                                                                                                      |
| Oracle       | `*.oraclecloud.com`                                                                                             | Required for Oracle Autonomous Database on OCI                                                                                           |

**AI specific requirements:**

The following egress domains are required depending on which AI provider you configure for [CARTO AI](https://docs.carto.com/carto-user-manual/settings/carto-ai). Only whitelist the domains for the providers you intend to use.

| Provider                                                                               | Domain(s)                            | Notes                                                                       |
| -------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
| [OpenAI](https://platform.openai.com/docs/api-reference)                               | `api.openai.com`                     | Not needed if configuring a custom Base URL to route through your own proxy |
| [Anthropic](https://docs.anthropic.com/en/api/getting-started)                         | `api.anthropic.com`                  |                                                                             |
| [Google AI Studio](https://ai.google.dev/gemini-api/docs)                              | `generativelanguage.googleapis.com`  | Gemini API                                                                  |
| [Google Vertex AI](https://cloud.google.com/vertex-ai/docs)                            | `*-aiplatform.googleapis.com`        | Region-specific subdomain (e.g., `us-central1-aiplatform.googleapis.com`)   |
| [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/)            | `*.openai.azure.com`                 | The exact domain depends on your Azure resource                             |
| [AWS Bedrock](https://docs.aws.amazon.com/bedrock/)                                    | See `*.amazonaws.com` above          | Covered in Cloud/Data warehouse section                                     |
| [Snowflake Cortex](https://docs.snowflake.com/en/user-guide/snowflake-cortex)          | See `*.snowflakecomputing.com` above | Covered in Cloud/Data warehouse section                                     |
| [Databricks](https://docs.databricks.com/en/machine-learning/model-serving/index.html) | See `*.databricks.com` above         | Covered in Cloud/Data warehouse section                                     |
| [Oracle GenAI](https://docs.oracle.com/en-us/iaas/Content/generative-ai/home.htm)      | See `*.oraclecloud.com` above        | Covered in Cloud/Data warehouse section                                     |
| Custom (OpenAI-compatible)                                                             | Your custom Base URL                 | Whitelist your endpoint's domain                                            |

**LDS specific requirements:**

These are the requirements for [Location Data Services](https://docs.carto.com/carto-for-developers/key-concepts/apis#location-data-services-lds):

| Domain                       | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `api.tomtom.com`             | Geocoding and routing                         |
| `api.traveltimeapp.com`      | Isolines                                      |
| `isoline.router.hereapi.com` | Isolines (if Here is the configured provider) |

{% hint style="info" %}
If you need further and more detailed information, please [contact us.](mailto:support@carto.com)
{% endhint %}

### External services required

Deploying CARTO Self-Hosted platform on cloud vendors like GCP, AWS, and Azure involves several external services and configurations. Below is a general guide to document the external services needed for deploying CARTO on these cloud platforms.

{% tabs %}
{% tab title="Google Cloud Platform (GCP)" %}

* **Compute Engine:** virtual machines for hosting CARTO. Just required if you'd like to deploy the single vm deployment in GCP.
* **GKE**: managed Kubernetes service for hosting CARTO orchestrated container deployment. Just required if you'd like to deploy the orchestrated container deployment in GCP.
* **Cloud Storage:** mandatory for storing data and configurations in GCP.
* **Cloud SQL:** managed database service for PostgreSQL mandatory for storing the metadata database.
* **Cloud DNS:** for managing domain names and DNS records.
  {% endtab %}

{% tab title="Amazon Web Services (AWS)" %}

* **EC2 Instances:** virtual machines for hosting CARTO. Just required if you'd like to deploy the single vm deployment in AWS.
* **EKS**: managed kubernetes service for hosting CARTO orchestrated container deployment. Just required if you'd like to deploy the orchestrated container deployment in AWS.
* **S3:** object storage for data. Mandatory if you'd like to store your data in AWS.
* **RDS:** managed database service for PostgreSQL. Mandatory in AWS for storing our metadata database.
* **Route 53:** mandatory for domain management and DNS if you're configuring it in AWS.
  {% endtab %}

{% tab title="Microsoft Azure" %}

* **Virtual Machines:** for hosting CARTO single vm deployment.
* **AKS:** for hosting CARTO orchestrated container deployment.
* **Azure Blob Storage:** for storing data and configurations.
* **Azure Database for PostgreSQL:** managed database service.
* **Azure DNS:** for domain management and DNS.
  {% endtab %}
  {% endtabs %}

### License requirements

A CARTO installation package that contains your environment configuration and a license key is required during the installation process. If you don't have these, you should request them at <support@carto.com>.


---

# Agent Instructions: 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:

```
GET https://docs.carto.com/carto-self-hosted/key-concepts/deployment-requirements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.