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 (Google Cloud Platform), AWS (Amazon Web Services), or Azure (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:

Requirements	AI Features disabled	AI Features enabled
CPU (x86)	8	16
Memory	32 GB	64 GB
Disk size	60	60

Orchestrated deployment (Kubernetes)

• Kubernetes 1.29 or above

• Helm 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 (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

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.

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.

• AWS: Amazon RDS for PostgreSQL.

• Azure: Azure Database for PostgreSQL.

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.

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

⚠️ Important Constraint ⚠️

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 ✅

  • Not valid: carto-prod-user, carto-maps ❌

⚠️ PostgreSQL Password Constraint ⚠️

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 ✅

  • Problematic: p@ss#word! ❌

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.

A full domain is required. You cannot install CARTO in a domain path like https://my.domain.com/carto

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

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
*.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
Google Cloud	storage.googleapis.com, www.googleapis.com	Access to CARTO platform buckets
AWS	*.amazonaws.com	Required for AWS S3 buckets
Azure	*.blob.core.windows.net	Required for Azure Blob storage
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. Only whitelist the domains for the providers you intend to use.

Provider	Domain(s)	Notes
OpenAI	api.openai.com	Not needed if configuring a custom Base URL to route through your own proxy
Anthropic	api.anthropic.com
Google AI Studio	generativelanguage.googleapis.com	Gemini API
Google Vertex AI	*-aiplatform.googleapis.com	Region-specific subdomain (e.g., us-central1-aiplatform.googleapis.com)
Azure OpenAI	*.openai.azure.com	The exact domain depends on your Azure resource
AWS Bedrock	See *.amazonaws.com above	Covered in Cloud/Data warehouse section
Snowflake Cortex	See *.snowflakecomputing.com above	Covered in Cloud/Data warehouse section
Databricks	See *.databricks.com above	Covered in Cloud/Data warehouse section
Oracle GenAI	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:

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

If you need further and more detailed information, please contact us.

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.

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.

Amazon Web Services (AWS)

Microsoft Azure

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 [email protected].