Architecture

How CARTO Self-Hosted fits together — components, data flow, and what runs where

CARTO Self-Hosted runs the full CARTO platform as a set of modular, containerized services on your own infrastructure. CARTO runs the application and platform services, while your geospatial data stays in your own data warehouse. The platform queries it at runtime rather than storing it.

The same components run regardless of the deployment method you choose. What changes is where they run, not what runs. This page is a high-level overview of how the pieces fit together, how a request flows through them, what you provide versus what CARTO includes, and how it all maps onto your infrastructure.

How it fits together

At a high level, a single entry point routes traffic to the web apps and APIs. Those services keep platform state in the metadata database, use the caches for repeated work, and hand off long-running jobs to background workers through the message broker. The actual geospatial data is queried from your data warehouse at runtime.

Platform components

CARTO is built from modular components, each mapping to a container in your deployment or to an external service you provide (such as the metadata database or in-memory cache).

Layer

Components

Role

Entry point

router-http

nginx reverse proxy — the single entry point that routes incoming HTTPS traffic to the right service.

Web applications

workspace-www, accounts-www

The Workspace UI (Builder, Workflows) and the login/signup app. Static React apps served by nginx.

APIs

workspace-api, maps-api, import-api, lds-api

Maps & SQL serving, imports, Location Data Services, and the Workspace backend. maps-api carries the heaviest traffic and is the one you scale out first.

Workers & subscribers

workspace-subscriber, import-worker, sql-worker, cdn-invalidator-sub

Consume queued messages to run imports, execute batch SQL, invalidate cached content, and sync workspace state.

Caching

http-cache, valkey

Varnish HTTP cache (CDN) for maps-api and some workspace-api responses, and an in-memory cache for APIs and subscribers.

Data layer

metadata-database, message-broker

PostgreSQL platform metadata and the producer/consumer message bus (Google Cloud Pub/Sub).

AI (optional)

ai-proxy, ai-api

LLM proxy and API — deployed only if you enable CARTO AI.

Management

kots

Admin Console containers — present only in the Single VM and Standard Orchestrated (Kots) methods.

The diagram below shows how these components connect. Each box maps to a container or an external service in your deployment.

CARTO Self-Hosted component architecture diagram showing the entry point, web apps, APIs, workers, caches, metadata database, and message broker

For a detailed description of every component, see the Component catalog.

How a request flows

Synchronous requests. A browser or API client reaches router-http, which routes the request to the matching web app or API. Read-heavy responses from maps-api (and some workspace-api endpoints) are served through the http-cache (Varnish) when possible. APIs check the in-memory cache (valkey) for hot lookups and intermediate results, falling back to the metadata database on a miss. When a request needs actual map or analytical data, maps-api queries your data warehouse directly and returns the result. The data is never copied into the platform.

Asynchronous jobs. Long-running operations don't block the request. The receiving API records the job and publishes a message to the message broker; a dedicated worker consumes it and does the work:

Operation

Producer

Consumer

What happens

Imports

import-api

import-worker

Reads the file from object storage and loads it into your data warehouse.

Batch SQL

maps-api

sql-worker

Runs batch SQL for PostgreSQL, Redshift, and Oracle warehouses. BigQuery, Snowflake, and Databricks use the warehouse's own batch APIs instead.

Cache invalidation

APIs

cdn-invalidator-sub

Purges affected content from the http-cache.

Workspace sync

platform events

workspace-subscriber

Applies account, user, and workspace changes to the metadata database.

What CARTO includes vs. what you provide

CARTO Self-Hosted ships the platform; you provide and operate the infrastructure it runs on and the systems that hold your data.

CARTO includes

You provide

The platform components — router, web apps, APIs, workers, and (for non-production setups) bundled PostgreSQL and Valkey

The compute to run it — a Single VM or a Kubernetes cluster

Container images, updates, and the Admin Console (Kots methods)

Your data warehouse connection (BigQuery, Snowflake, Redshift, PostgreSQL, Databricks, or Oracle)

Configuration tooling (Kots UI or Helm charts)

Object storage buckets, DNS and TLS certificates, and — for production — an external metadata database and in-memory cache

Your data warehouse and object storage stay under your control; CARTO connects to them but does not manage them.

Deployment architectures

The CARTO components above run the same way on every cloud, and the infrastructure around them varies. The diagrams below show reference architectures for each cloud provider across both deployment methods: Single Virtual Machine (embedded cluster, Kots-managed) and Orchestrated container deployment (Kubernetes, Kots or Helm).

These are reference architectures, not step-by-step guides. For detailed install instructions, see the Deployment Guides. For cloud-specific best practices (instance types, managed services, networking), see Deployment best practices.

Single Virtual Machine deployment