🛞Advanced Orchestrated container deployment

Get CARTO Self-Hosted running on Kubernetes with Helm in the shortest time possible

Advanced Orchestrated container deployment

Estimated time: ~45–60 minutes

This quickstart walks you through the minimum steps to deploy CARTO Self-Hosted on a Kubernetes cluster using Helm. It uses default values wherever possible to reduce time-to-deployment.

For a full production-ready installation with all configuration options, see the Advanced Orchestrated container deployment guide.

Quickstarts are not suitable for production. For a production-grade installation with full configuration options, use the Deployment Guides.

Before you begin

Complete every item below before starting. Each prerequisite has a dedicated setup guide. Do not skip them.

• License & customer package (carto-values.yaml + carto-secrets.yaml) received from CARTO Support → License / Customer Package

• Kubernetes cluster meets the hardware requirements for Advanced Orchestrated deployments → Hardware & Software Requirements

• Metadata database (PostgreSQL 14+) provisioned and accessible from the cluster → Metadata Database prerequisites

• Object storage buckets created, CORS configured, and IAM permissions set → Object Storage prerequisites

• Network egress open for all required CARTO services → Network egress requirements

• kubectl and helm v3.6+ installed and connected to your cluster

• A domain name and TLS certificate ready

Steps

1. Create the CARTO namespace

kubectl create namespace carto

2. Create your customizations.yaml

Create a new file called customizations.yaml in the same directory as your customer package files.

2.1 Domain and database

# customizations.yaml

appConfigValues:
  selfHostedDomain: "carto.yourcompany.com"  # Replace with your domain

# External PostgreSQL connection
internalPostgresql:
  enabled: false
externalPostgresql:
  host: "your-postgres-host"
  port: "5432"
  database: "carto_workspace"
  user: "carto_workspace_admin"
  existingSecret: "carto-postgresql"
  existingSecretPasswordKey: "user-password"

Supply the database password via a Kubernetes secret, not as plaintext. Create the secret before installing:

kubectl create secret generic carto-postgresql \
  --namespace carto \
  --from-literal=user-password="<your-db-password>"

2.2 Object storage

Make sure your buckets are already created and CORS is configured (see Object Storage prerequisites). Then add the storage configuration to your customizations.yaml for your cloud provider:

Google Cloud Storage

appConfigValues:
  storageProvider: "gcp"
  workspaceImportsBucket: <import_bucket_name>
  workspaceImportsPublic: "false"
  workspaceThumbnailsBucket: <thumbnails_bucket_name>
  workspaceThumbnailsPublic: "true"
  thumbnailsBucketExternalURL: https://storage.googleapis.com/<thumbnails_bucket_name>/
  googleCloudStorageProjectId: <gcp_project_id>
appSecrets:
  googleCloudStorageServiceAccountKey:
    value: |
      <paste your service account JSON key>

AWS S3

Azure Blob Storage

For full bucket configuration options including keyless auth (Workload Identity, EKS Pod Identity) and export bucket setup, see Configure your own buckets.

3. Add the CARTO Helm repository

helm repo add carto https://helm.carto.com
helm repo update carto

4. Install CARTO with Helm

helm install carto carto/carto \
  --namespace carto \
  -f carto-values.yaml \
  -f carto-secrets.yaml \
  -f customizations.yaml

5. Watch the rollout

kubectl rollout status deployment -n carto
kubectl get pods -n carto

All pods should reach Running status. This may take 3–5 minutes on first install.

6. Set up domain access

Once the deployment is running, get your cluster's load balancer IP or hostname:

kubectl get svc carto-router -n carto

Option A — Cloud cluster with a LoadBalancer IP/hostname:

Map the domain to the external IP in /etc/hosts for a quick local test:

echo '34.x.x.x carto.yourcompany.com' >> /etc/hosts

Option B — Local cluster or no LoadBalancer (kind, minikube, etc.):

Use kubectl port-forward to access CARTO directly on localhost:

kubectl port-forward -n carto svc/carto-router 8080:80

Then open http://localhost:8080 in your browser (no TLS in this mode).

For production DNS setup, see Load Balancing best practices.

Verify first success

Once deployment completes, confirm the following:

• All pods are running: kubectl get pods -n <namespace>

• The CARTO application loads at your configured domain over HTTPS

• You can log in with your admin credentials

• A basic map renders successfully

If any check fails, see Troubleshooting and Debug mode and logs.

Next steps

For a production-ready installation with full configuration options, use the Advanced Orchestrated container deployment guide.