Single VM deployment (Kots)
Deploy CARTO Self-hosted using a Virtual Machine, k0s, and Kots
Last updated
Was this helpful?
Deploy CARTO Self-hosted using a Virtual Machine, k0s, and Kots
Last updated
Was this helpful?
The goal of this article is to guide system administrators through the complete deployment of CARTO Self-Hosted using a Single Virtual Machine in a cloud environment such as GCP, AWS, or Azure. The scope includes all necessary steps and requirements to prepare the environment, install and configure the CARTO platform, connect it to an external PostgreSQL metadata database, enable secure HTTPS access with a valid domain and SSL certificate, set up cloud storage integration, and verify the deployment through post-installation checks.
To deploy CARTO Self-Hosted based on a Single VM deployment, you need:
Access to the CARTO Self-Hosted installation package, including your license file. If you haven’t received it, you can request it by contacting support@carto.com.
A domain name that you own and can configure with custom DNS records.
An SSL/TLS certificate for your domain, as CARTO must be accessed over HTTPS.
A virtual machine that meets the minimum required for Single VM deployments.
A review and understanding of the requirements to configure external cloud storage.
Familiarity as a SysAdmin in the cloud environment where you are running your installation: GCP, AWS, or Azure.
CARTO Self-Hosted can be deployed in any Virtual Machine that meets the minimum requirements specified for .
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.
Download the customer package from the URL that shared by CARTO team. Select the CARTO Embedded Cluster installation and download the binary.
Extract the package content using the following command:
During the installation process of CARTO Self-Hosted, you will be prompted to set a password for accessing the Admin Console. This console serves as the control center for managing various deployment options related to your CARTO instance. It is crucial to securely store this password for future access and administration tasks.
After accessing the URL, you'll need to configure an SSL certificate for the Admin Console.
Once the SSL certificate is configured, proceed by clicking the continue button to confirm the configuration of your cluster. You can then begin customizing the settings and features of your CARTO Self-Hosted platform through the Admin Console.
In order to enable TLS connections, you'll also have to provide the SSL certificate of your PostgreSQL database.
Mutual TLS connections between the external database and the APIs are not supported, so client certificates can't be configured on your external database
In order to access CARTO Self-Hosted platform, you'll need a domain pointing to the IP address of the machine where you're deploying the platform. This domain has to be defined in the following section of the configuration:
The CARTO platform necessitates a valid SSL certificate tailored to your domain to ensure secure communication and data transfer. Depending on your architecture, you have the flexibility to either terminate TLS within the CARTO application, requiring your SSL certificate, or at a higher layer.
A valid certificate contains:
A .crt file with your custom domain x509 certificate.
A .key file with your custom domain private key.
Once the configuration has been updated, you'll need 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:
CARTO Self-hosted platform requires access to some storage buckets to save some resources required 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:
After finalizing your configuration, proceed by clicking the “Continue” button, which will direct you to the Dashboard of your CARTO Admin Console. Here, you'll observe a series of checks being performed to verify the readiness of your environment for hosting the CARTO platform.
It's essential to review the results of these checks to identify any failures. If all checks pass successfully, you can proceed by clicking the “Deploy” button to initiate the installation process of your Self-Hosted platform. Please, note that deployment completion may take a few minutes.
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.
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:
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:
From the Admin Console you'll be able to analyze your CARTO installation by clicking on the Troubleshoot section. You can generate a support bundle from this view, that will collect all the required information to check the status of your deployment.
Check that your machine meets the and install the CARTO Self-Hosted platform Admin Console with the following command:
Upon completion of the installation, you can access the Admin Console through your server's IP address and port 30000 by navigating to .
At this point, we are setting up the configuration of the . You need to provide a PostgreSQL user and a database that can be used by that user to configure the metadata database used by CARTO platform.
If you already have a PostgreSQL deployment that can be used by your CARTO Self-Hosted platform, you'll have to for CARTO platform and a user with enough permissions to use that database.
And in order to configure them, there is a available that you should follow to complete the Self-Hosted configuration process.
If you'd like to enable the onboarding experience and the Data Observatory features, follow the or contact .
For further assistance, check our page.
