This documentation is for the CARTO Self-Hosted Legacy Version. Use only if you've installed this specific version. Explore our latest documentation for updated features.
To deploy CARTO Self-Hosted based on a Single VM deployment, you need:
A CARTO Self-Hosted installation package containing your environment configuration and a license key. The package has two files: customer.env and key.json. If you don't have it yet, you can ask for it at .
A domain you own, to which you can add a DNS record.
Familiarity with and installations of and .
CARTO Self-Hosted can be deployed in any Virtual Machine that meets the minimum requirements specified at ).
Create a new Linux VM in the that meets the minimum requirements specified at ).
Refer to the to learn how to create a new virtual machine.
Configure the firewall to allow HTTPS traffic.
Specify SSD persistent with a size that meets or exceeds the minimum requirements.
Create a new Linux EC2 instance in the using the Ubuntu Server 22.04 LTS (x86) Amazon Machine Image (AMI).
Once, your VM is ready, you should log in via SSH and install the latest version of and .
Clone this repository:
Checkout to the :
Copy into carto-selfhosted folder the two files of the installation package
customer.env
key.json
Configure your CARTO Self-hosted domain by updating the env var SELFHOSTED_DOMAIN to my.domain.com.
Create a DNS record that points my.domain.com to the External IP of your VM. For debugging purposes, you might want to modify your /etc/hosts:
Add to customer.env the configuration of the . At this point, you need to provide a PostgreSQL admin user (typically postgres) with permission to create users and databases.
POSTGRES_ADMIN_USER: Your PostgreSQL admin user.
POSTGRES_ADMIN_PASSWORD: The password of your admin user.
WORKSPACE_POSTGRES_USER: The admin user to be created. It will be created with the previous admin user.
WORKSPACE_POSTGRES_PASSWORD: The new password to be created.
In some scenarios, it's required an SSL connection between the external database and the APIs. In that case, you should provide the SSL certificate and add to customer.env the SSL configuration of your server.
Mutual TLS connections between the external database and the APIs are not supported, so client certificates can't be configured on your external database
You should copy your certificate in .pem format into the certs folder located inside your installation route. We'll automatically mount the whole certs folder inside the required containers so that they can use the SSL certificate.
Run the install.sh script to generate the .env file out of the customer.env file:
Bring up the environment:
Check all the containers are up and running:
A non-production-ready deployment of CARTO should be available at https://my.domain.com.
CARTO Self-hosted platform needs access to some storage buckets to save some resources needed by the platform. These buckets are in charge of storing assets such as imported datasets, map snapshots and custom markers.
You can create and use your own storage buckets in any of the following supported storage providers:
And in order to configure them, there is a available that you should follow to complete the Self-Hosted configuration process.
By default, CARTO Self-hosted will generate and use a self-signed certificate. In production environments, you need to provide your own SSL certificate.
A valid certificate contains:
A .crt file with your custom domain x509 certificate.
A .key file with your custom domain private key.
Create a certs folder in the current directory (carto-selfhosted)
Copy your <cert>.crt and <cert>.key files in the certs folders
Modify the following vars in the customer.env
Refresh:
In order to verify CARTO Self Hosted was correctly installed, and it's functional, we recommend performing the following checks:
Sign in to your Self Hosted, create a user and a new organization.
Go to the Connections page, in the left-hand menu, create a new connection to one of the available providers.
Go to the Data Explorer page, click on the Upload button right next to the Connections panel. Import a dataset from a local file.
Create a new layer from the dataset imported in step 4.
Make the map public, copy the sharing URL, and open it in a new incognito window.
Go back to the Maps page, and verify your map appears there, and the map thumbnail represents the latest changes you made to the map.
Congrats! Once you've configured your custom buckets, you should have a production-ready deployment of CARTO Self-Hosted at https://my.domain.com
To fully leverage CARTO's capabilities you need to gain access to the Analytics Toolbox functions. This step is crucial to fully leverage CARTO's capabilities. Please refer to the documentation of your data warehouse provider for detailed instructions:
The installation of CARTO Self-Hosted doesn't require root privileges. It can be performed using a regular system user with permission to execute the docker and docker-compose binaries.
This means that once the dependencies and prerequisites are satisfied, the operator that runs the installation only requires permission to run the docker and docker-compose binaries.
This is usually achieved by adding the system user to the docker group, but there is more detailed information .
The following standard commands of docker-compose could be used to debug possible issues that might arise:
docker-compose logs and docker-compose ps
The container workspace-migrations will be responsible for creating a new user carto_worskpace_admin and a database carto_workspace.
To debug possible errors with the connection of the external database, you might need to check the logs of this container:
For further assistance, check our page.
Familiarity as a SysAdmin in the cloud environment where you are running your installation: GCP, AWS, or Azure.
​Configure the firewall to allow HTTPS traffic.
Specify SSD persistent with a size that meets or exceeds the minimum requirements.
Create a new Linux VM in the Azure Portal that meets the minimum requirements.
Refer to the Azure documentation to learn how to create a new virtual machine.
​Configure the firewall to allow HTTPS traffic.
When creating the VM, use SSH public key authentication and provide a username. Generate a new key-pair and specify a name. Azure generates and stores the key in the Azure KeyVault to download later.​
Specify SSD persistent with a size that meets or exceeds the minimum requirements.
Once the VM is initialized, download the private key when prompted. Update the permissions of the key-pair to ensure it has the required permissions for your SSH client.
Ensure Delete public IP and NIC when VM is deleted is enabled.
WORKSPACE_POSTGRES_DB: The database to be created.
Go back to the Maps page, and create a new map.
In this new map, add a new layer from a table using the connection created in step 3.
Create a new layer from a SQL Query to the same table. You can use a simple query like:
This documentation is for the CARTO Self-Hosted Legacy Version. Use only if you've installed this specific version. Explore our latest documentation for updated features.
git clone https://github.com/CartoDB/carto-selfhosted.git
cd carto-selfhostedgit checkout tags/2025.11.11echo "34.172.214.74 my.domain.com" >> /etc/hosts# Set to 0 to not create the PostgreSQL container locally
LOCAL_POSTGRES_SCALE=0
WORKSPACE_POSTGRES_HOST=<YourServerIP>
WORKSPACE_POSTGRES_PORT=5432
WORKSPACE_POSTGRES_USER=carto_worskpace_admin
WORKSPACE_POSTGRES_PASSWORD=carto_worskpace_admin
WORKSPACE_POSTGRES_DB=carto_worskpace
# SSL will be enabled later.
WORKSPACE_POSTGRES_SSL_ENABLED=false
WORKSPACE_POSTGRES_SSL_MODE=disable
POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgresWORKSPACE_POSTGRES_SSL_ENABLED=true
WORKSPACE_POSTGRES_SSL_MODE=require
# Only applies if Postgres SSL certificate is self-signed
WORKSPACE_POSTGRES_SSL_CA=/usr/src/certs/<CERTIFICATE_NAME>.pembash install.shdocker-compose up -ddocker-compose psopenssl rsa -in keyfile_with_passphrase.key -out new_keyfile.keybash install.sh
docker-compose up -d SELECT * FROM <dataset_name.table_name> LIMIT 100;docker-compose logs workspace-migrationsROUTER_SSL_AUTOGENERATE=0
ROUTER_SSL_CERTIFICATE_PATH=/etc/nginx/ssl/my.domain.com.crt
ROUTER_SSL_CERTIFICATE_KEY_PATH=/etc/nginx/ssl/my.domain.com.key
chmod 400 <path_to_pem_file>
ssh -i <path_to_pem_file> <username>@<public_ip>