LogoLogo
HomeAcademyLoginTry for free
  • Welcome
  • What's new
    • Q2 2025
    • Q1 2025
    • Q4 2024
    • Q3 2024
    • Q2 2024
    • Q1 2024
    • Q4 2023
    • Q3 2023
    • Q2 2023
    • Q1 2023
    • Q4 2022
    • Q3 2022
  • FAQs
    • Accounts
    • Migration to the new platform
    • User & organization setup
    • General
    • Builder
    • Workflows
    • Data Observatory
    • Analytics Toolbox
    • Development Tools
    • Deployment Options
    • CARTO Basemaps
    • CARTO for Education
    • Support Packages
    • Security and Compliance
  • Getting started
    • What is CARTO?
    • Quickstart guides
      • Connecting to your data
      • Creating your first map
      • Creating your first workflow
      • Developing your first application
    • CARTO Academy
  • CARTO User Manual
    • Overview
      • Creating your CARTO organization
      • CARTO Cloud Regions
      • CARTO Workspace overview
    • Maps
      • Data sources
        • Simple features
        • Spatial Indexes
        • Pre-generated tilesets
        • Rasters
        • Defining source spatial data
        • Managing data freshness
        • Changing data source location
      • Layers
        • Point
          • Grid point aggregation
          • H3 point aggregation
          • Heatmap point aggregation
          • Cluster point aggregation
        • Polygon
        • Line
        • Grid
        • H3
        • Raster
        • Zoom to layer
      • Widgets
        • Formula widget
        • Category widget
        • Pie widget
        • Histogram widget
        • Range widget
        • Time Series widget
        • Table widget
      • SQL Parameters
        • Date parameter
        • Text parameter
        • Numeric parameter
        • Publishing SQL parameters
      • Interactions
      • Legend
      • Basemaps
        • Basemap selector
      • AI Agents
      • SQL analyses
      • Map view modes
      • Map description
      • Feature selection tool
      • Search locations
      • Measure distances
      • Exporting data
      • Download PDF reports
      • Managing maps
      • Publishing and sharing maps
        • Map settings for viewers
        • Map preview for editors
        • Collaborative maps
        • Embedding maps
        • URL parameters
      • Performance considerations
    • Workflows
      • Workflow canvas
      • Results panel
      • Components
        • Aggregation
        • Custom
        • Data Enrichment
        • Data Preparation
        • Generative AI
        • Input / Output
        • Joins
        • Parsers
        • Raster Operations
        • Spatial Accessors
        • Spatial Analysis
        • Spatial Constructors
        • Spatial Indexes
        • Spatial Operations
        • Statistics
        • Tileset Creation
        • BigQuery ML
        • Snowflake ML
        • Google Earth Engine
        • Google Environment APIs
        • Telco Signal Propagation Models
      • Data Sources
      • Scheduling workflows
      • Sharing workflows
      • Using variables in workflows
      • Executing workflows via API
      • Temporary data in Workflows
      • Extension Packages
      • Managing workflows
      • Workflows best practices
    • Data Explorer
      • Creating a map from your data
      • Importing data
        • Importing rasters
      • Geocoding data
      • Optimizing your data
    • Data Observatory
      • Terminology
      • Browsing the Spatial Data Catalog
      • Subscribing to public and premium datasets
      • Accessing free data samples
      • Managing your subscriptions
      • Accessing your subscriptions from your data warehouse
        • Access data in BigQuery
        • Access data in Snowflake
        • Access data in Databricks
        • Access data in Redshift
        • Access data in PostgreSQL
    • Connections
      • Google BigQuery
      • Snowflake
      • Databricks
      • Amazon Redshift
      • PostgreSQL
      • CARTO Data Warehouse
      • Sharing connections
      • Deleting a connection
      • Required permissions
      • IP whitelisting
      • Customer data responsibilities
    • Applications
    • Settings
      • Understanding your organization quotas
      • Activity Data
        • Activity Data Reference
        • Activity Data Examples
        • Activity Data Changelog
      • Users and Groups
        • Inviting users to your organization
        • Managing user roles
        • Deleting users
        • SSO
        • Groups
        • Mapping groups to user roles
      • CARTO Support Access
      • Customizations
        • Customizing appearance and branding
        • Configuring custom color palettes
        • Configuring your organization basemaps
        • Enabling AI Agents
      • Advanced Settings
        • Managing applications
        • Configuring S3 Bucket for Redshift Imports
        • Configuring OAuth connections to Snowflake
        • Configuring OAuth U2M connections to Databricks
        • Configuring S3 Bucket integration for RDS for PostgreSQL Exports in Builder
        • Configuring Workload Identity Federation for BigQuery
      • Data Observatory
      • Deleting your organization
    • Developers
      • Managing Credentials
        • API Base URL
        • API Access Tokens
        • SPA OAuth Clients
        • M2M OAuth Clients
      • Named Sources
  • Data and Analysis
    • Analytics Toolbox Overview
    • Analytics Toolbox for BigQuery
      • Getting access
        • Projects maintained by CARTO in different BigQuery regions
        • Manual installation in your own project
        • Installation in a Google Cloud VPC
        • Core module
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • cpg
        • data
        • http_request
        • import
        • geohash
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • routing
        • s2
        • statistics
        • telco
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release notes
      • About Analytics Toolbox regions
    • Analytics Toolbox for Snowflake
      • Getting access
        • Native App from Snowflake's Marketplace
        • Manual installation
      • Key concepts
        • Spatial indexes
        • Tilesets
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • data
        • http_request
        • import
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release Notes
    • Analytics Toolbox for Databricks
      • Getting access
        • Personal (former Single User) cluster
        • Standard (former Shared) cluster
      • Reference
        • lds
        • tiler
      • Guides
      • Release Notes
    • Analytics Toolbox for Redshift
      • Getting access
        • Manual installation in your database
        • Installation in an Amazon Web Services VPC
        • Core version
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • clustering
        • constructors
        • data
        • http_request
        • import
        • lds
        • placekey
        • processing
        • quadbin
        • random
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
      • Release Notes
    • Analytics Toolbox for PostgreSQL
      • Getting access
        • Manual installation
        • Core version
      • Key concepts
        • Tilesets
        • Spatial Indexes
      • SQL Reference
        • h3
        • quadbin
        • tiler
      • Guides
        • Creating spatial index tilesets
        • Running queries from Builder
      • Release Notes
    • CARTO + Python
      • Installation
      • Authentication Methods
      • Visualizing Data
      • Working with Data
        • How to work with your data in the CARTO Data Warehouse
        • How to access your Data Observatory subscriptions
        • How to access CARTO's Analytics Toolbox for BigQuery and create visualizations via Python notebooks
        • How to access CARTO’s Analytics Toolbox for Snowflake and create visualizations via Python notebooks
        • How to visualize data from Databricks
      • Reference
    • CARTO QGIS Plugin
  • CARTO for Developers
    • Overview
    • Key concepts
      • Architecture
      • Libraries and APIs
      • Authentication methods
        • API Access Tokens
        • OAuth Access Tokens
        • OAuth Clients
      • Connections
      • Data sources
      • Visualization with deck.gl
        • Basemaps
          • CARTO Basemap
          • Google Maps
            • Examples
              • Gallery
              • Getting Started
              • Basic Examples
                • Hello World
                • BigQuery Tileset Layer
                • Data Observatory Tileset Layer
              • Advanced Examples
                • Arc Layer
                • Extrusion
                • Trips Layer
            • What's New
          • Amazon Location
            • Examples
              • Hello World
              • CartoLayer
            • What's New
        • Rapid Map Prototyping
      • Charts and widgets
      • Filtering and interactivity
      • Summary
    • Quickstart
      • Make your first API call
      • Visualize your first dataset
      • Create your first widget
    • Guides
      • Build a public application
      • Build a private application
      • Build a private application using SSO
      • Visualize massive datasets
      • Integrate CARTO in your existing application
      • Use Boundaries in your application
      • Avoid exposing SQL queries with Named Sources
      • Managing cache in your CARTO applications
    • Reference
      • Deck (@deck.gl reference)
      • Data Sources
        • vectorTableSource
        • vectorQuerySource
        • vectorTilesetSource
        • h3TableSource
        • h3QuerySource
        • h3TilesetSource
        • quadbinTableSource
        • quadbinQuerySource
        • quadbinTilesetSource
        • rasterSource
        • boundaryTableSource
        • boundaryQuerySource
      • Layers (@deck.gl/carto)
      • Widgets
        • Data Sources
        • Server-side vs. client-side
        • Models
          • getFormula
          • getCategories
          • getHistogram
          • getRange
          • getScatter
          • getTimeSeries
          • getTable
      • Filters
        • Column filters
        • Spatial filters
      • CARTO APIs Reference
    • Release Notes
    • Examples
    • CARTO for React
      • Guides
        • Getting Started
        • Views
        • Data Sources
        • Layers
        • Widgets
        • Authentication and Authorization
        • Basemaps
        • Look and Feel
        • Query Parameters
        • Code Generator
        • Sample Applications
        • Deployment
        • Upgrade Guide
      • Examples
      • Library Reference
        • Introduction
        • API
        • Auth
        • Basemaps
        • Core
        • Redux
        • UI
        • Widgets
      • Release Notes
  • CARTO Self-Hosted
    • Overview
    • Key concepts
      • Architecture
      • Deployment requirements
    • Quickstarts
      • Single VM deployment (Kots)
      • Orchestrated container deployment (Kots)
      • Advanced Orchestrated container deployment (Helm)
    • Guides
      • Guides (Kots)
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Use Workload Identity in GCP
        • High availability configuration for CARTO Self-hosted
        • Configure your custom service account
      • Guides (Helm)
        • Configure your own buckets (Helm)
        • Configure an external in-memory cache (Helm)
        • Enable Google Basemaps (Helm)
        • Enable the CARTO Data Warehouse (Helm)
        • Configure an external proxy (Helm)
        • Enable BigQuery OAuth connections (Helm)
        • Configure Single Sign-On (SSO) (Helm)
        • Use Workload Identity in GCP (Helm)
        • Use EKS Pod Identity in AWS (Helm)
        • Enable Redshift imports (Helm)
        • Migrating CARTO Self-hosted installation to an external database (Helm)
        • Advanced customizations (Helm)
        • Configure your custom service account (Helm)
    • Maintenance
      • Maintenance (Kots)
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
        • Change the Admin Console password
      • Maintenance (Helm)
        • Monitoring (Helm)
        • Rotating keys (Helm)
        • Uninstall (Helm)
        • Backups (Helm)
        • Updates (Helm)
    • Support
      • Get debug information for Support (Kots)
      • Get debug information for Support (Helm)
    • CARTO Self-hosted Legacy
      • Key concepts
        • Architecture
        • Deployment requirements
      • Quickstarts
        • Single VM deployment (docker-compose)
      • Guides
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Enable Redshift imports
        • Configure your custom service account
        • Advanced customizations
        • Migrating CARTO Self-Hosted installation to an external database
      • Maintenance
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
      • Support
    • Release Notes
  • CARTO Native App for Snowflake Containers
    • Deploying CARTO using Snowflake Container Services
  • Get Help
    • Legal & Compliance
    • Previous libraries and components
    • Migrating your content to the new CARTO platform
Powered by GitBook
On this page
  • Requirements
  • Create a Linux VM instance​
  • Installation steps
  • Install Admin Console
  • Metadata database
  • Access to CARTO
  • Cloud Storage
  • Deploy CARTO Self-Hosted platform
  • Post-installation checks
  • Analytics Toolbox in CARTO Self-Hosted
  • Troubleshooting

Was this helpful?

Export as PDF
  1. CARTO Self-Hosted
  2. Quickstarts

Single VM deployment (Kots)

Deploy CARTO Self-hosted using a Virtual Machine, k0s, and Kots

PreviousQuickstartsNextOrchestrated container deployment (Kots)

Last updated 1 year ago

Was this helpful?

Estimated time: Completing this deployment guide is expected to take approximately 2 hours. This estimate may vary based on individual familiarity with the technology stack involved and the complexity of your organization's environment.

Requirements

To deploy CARTO Self-Hosted based on a Single VM deployment, you need:

  • A link to the CARTO Self-Hosted installation package containing your license. 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 as a SysAdmin in the cloud environment where you are running your installation: GCP, AWS, or Azure.

Create a Linux VM instance

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.

Create a new Linux EC2 instance in the using the Ubuntu Server 22.04 LTS (x86) Amazon Machine Image (AMI).

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 VM in the that meets the minimum requirements.

Refer to the 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.

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.

Installation steps

Install Admin Console

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:

tar -xvf carto.tgz
sudo ./carto install --license license.yaml

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.

sudo ./carto install --license license.yaml
? Enter a new Admin Console password: ********
? Confirm password: ********
✔  Node installation finished
✔  Storage is ready!
✔  Embedded Cluster Operator is ready!
✔  Admin Console is ready!
Admin Console accessible at: http://your_ip:30000

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.

Metadata database

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

Access to CARTO

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:

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

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.

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

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:

echo "34.172.214.74 my.domain.com" >> /etc/hosts

Cloud Storage

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:

Deploy CARTO Self-Hosted platform

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.

Post-installation checks

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 Connections page, in the left-hand menu, create a new connection to one of the available providers.

  3. Go to the Data Explorer page, click on the Upload button right next to the Connections panel. Import a dataset from a local file.

  4. Go back to the Maps page, 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;
  1. Create a new layer from the dataset imported in step 4.

  2. Make the map public, copy the sharing URL, and open it in a new incognito window.

  3. 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

You may notice that the onboarding experience (demo maps, demo workflows...) and the Data Observatory-automated features (subscriptions, enrichment...) are disabled by default in your new organization, because the CARTO Data Warehouse is not enabled.

If you prefer not to enable the CARTO Data Warehouse, you can still use the Data Observatory without the UI features: after getting in touch, our team can deliver the data (both premium and public subscriptions) manually to your data warehouse.

Analytics Toolbox in CARTO Self-Hosted

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:

Troubleshooting

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.

deployment requirements
http://your-server-ip:30000
create a new database
Google Cloud Storage
AWS S3
Azure Blob Storage
detailed guide
guide to enable the CARTO Data Warehouse
support@carto.com
Google BigQuery
Amazon Redshift
Snowflake
PostgreSQL
Support
support@carto.com
​
Google Cloud console
Google Cloud documentation
​
Amazon EC2 console
Amazon EC2 documentation
​
Azure Portal
Azure documentation
​
​
Single VM deployments
Single VM deployments
external database