Comment on page
Single VM deployment
Deploy CARTO Self-hosted using a Virtual Machine and Docker Compose
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:
key.json. If you don't have it yet, you can ask for it at [email protected].
- A domain you own, to which you can add a DNS record.
Google Cloud GCP Instance
AWS EC2 Instance
- 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.
chmod 400 <path_to_pem_file>
ssh -i <path_to_pem_file> <username>@<public_ip>
Ensure Delete public IP and NIC when VM is deleted is enabled.
Clone this repository:
git clone https://github.com/CartoDB/carto-selfhosted.git
git checkout tags/2023.10.25
carto-selfhostedfolder the two files of the installation package
Configure your CARTO Self-hosted domain by updating the env var
A full domain is required. You cannot install CARTO in a domain path like https://my.domain.com/carto
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:
echo "188.8.131.52 my.domain.com" >> /etc/hosts
- 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.
- WORKSPACE_POSTGRES_DB: The database to be created.
For Azure Postgres instances you'll need a couple of extra env vars
- WORKSPACE_POSTGRES_INTERNAL_USER: Same value as
WORKSPACE_POSTGRES_USERbut without the
- POSTGRES_LOGIN_USER: Same value as
POSTGRES_ADMIN_USERbut without the
# Set to 0 to not create the PostgreSQL container locally
# SSL will be enabled later.
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.
# Only applies if Postgres SSL certificate is self-signed
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
.pemformat into the
certsfolder located inside your installation route. We'll automatically mount the whole
certsfolder inside the required containers so that they can use the SSL certificate.
install.shscript to generate the
.envfile out of the
Bring up the environment:
docker-compose up -d
Check all the containers are up and running:
All containers should be in the state
Up, except for
workspace-migrationswhich state should be
Exit 0, meaning the database migrations finished correctly.
A non-production-ready deployment of CARTO should be available at
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:
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:
.crtfile with your custom domain x509 certificate.
.keyfile with your custom domain private key.
If your TLS certificate key is protected with a passphrase the CARTO Self-hosted installation won't be able to work as expected. You can easily generate a new key file without passphrase protection using the following command:
openssl rsa -in keyfile_with_passphrase.key -out new_keyfile.key
- 1.Create a
certsfolder in the current directory (
- 2.Copy your
<cert>.keyfiles in the
- 3.Modify the following vars in the
docker-compose up -d
In order to verify CARTO Self Hosted was correctly installed, and it's functional, we recommend performing the following checks:
- 1.Sign in to your Self Hosted, create a user and a new organization.
- 2.Go to the
Connectionspage, in the left-hand menu, create a new connection to one of the available providers.
- 3.Go to the
Data Explorerpage, click on the
Uploadbutton right next to the
Connectionspanel. Import a dataset from a local file.
- 4.Go back to the
Mapspage, and create a new map.
- 5.In this new map, add a new layer from a table using the connection created in step 3.
- 6.Create a new layer from a SQL Query to the same table. You can use a simple query like:
SELECT * FROM <dataset_name.table_name> LIMIT 100;
- 7.Create a new layer from the dataset imported in step 4.
- 8.Make the map public, copy the sharing URL, and open it in a new incognito window.
- 9.Go back to the
Mapspage, 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
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
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.
The following standard commands of docker-compose could be used to debug possible issues that might arise:
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:
docker-compose logs workspace-migrations