Configure CARTO AI Prerequisites Helm)

In this post you'll find all you need to do to enable the AI Features in Self-Hosted using Helm.

This guide provides instructions for enabling the necessary prerequisites to run CARTO AI features in a Self-Hosted environment managed via Helm. It covers configuration changes, deployment steps, and validation of the AI proxy resources.

1. Requirements

Before modifying the Helm configuration, you must prepare your database and network environment.

1.1 Check that an external database is configured

To setup AI Features in CARTO Self-Hosted you need to already be using an external PostgreSQL metadata database. In legacy versions of CARTO Self-Hosted we provided an internal database that could be deployed as part of our Helm chart. If you're still using it, please get in touch with CARTO Support team to plan the migration to an external database.

You can verify if you're using the internal database with the following command:

helm get values -n <namespace> <release-name> -o yaml | yq '.internalPostgresql.enabled'

1.2. Create 'aiproxy' database

The AI Proxy service requires its own dedicated logical database within your PostgreSQL instance. The default recommended name is aiproxy.

• Connect to your PostgreSQL instance and run:

CREATE DATABASE aiproxy;

1.3. Identify the database user

You must identify the specific database user currently configured for your deployment to grant it permissions later.

1.3.1 Connect to Kubernetes Cluster

• Connect to your Kubernetes cluster where CARTO is deployed using kubectl cli tool .

• Verify connection: check that you are in the correct cluster.

kubectl cluster-info kubectl config current-context

• List namespaces to find your deployment:

kubectl get namespaces

• Note the CARTO namespace <namespace>.

1.3.2 Find your Helm Release

• Make sure that you have helm cli tool installed .

• Run the following Helm command to get the release name:

helm list -A

• Note the CARTO release name <release-name> (first column named "NAME").

1.3.3 Get the Metadata Database user name:

1. Based on the previous information about the release name:

helm get values -n <namespace> <release-name> -o yaml | yq '.externalPostgresql.user'

1.3 Grant owner permissions

The database user identified in the previous step must have ownership permissions over the new AI database. Replace <carto_user> with the user you identified in step 1.2.

GRANT ALL PRIVILEGES ON DATABASE llmproxy TO <carto_user>;
ALTER DATABASE llmproxy OWNER TO <carto_user>;

1.4 Increase load balancer timeout

AI-generated responses often require longer processing times than standard HTTP requests. As those requests usually take less than 1 minute, but they can go up to 5 minutes, it's required to allow longer requests for the CARTO Self-Hosted platform.

Therefore, you'll have to increase the idle timeout on the Load Balancer exposing the CARTO service to allow requests taking up to 300 seconds (5 minutes).

CARTO already manages expected timeouts for each API at the service level to ensure that requests taking longer than expected don't block the operations performed by the platform, so it's not required to specify different timeout values depending on the request at your load balancer level.

Note: This configuration varies by provider (e.g., idle_timeout.timeout_seconds in AWS ALB, or keepalive_timeout in NGINX). You need to handle this configuration in your respective setup.

2. Modify 'customizations.yaml' file

Now that all prerequisites are met we can enable the AI Pre-requisites in the Helm Chart.

• Add the following lines to your customization.yaml file:

appConfigValues:
  ## Enable CARTO AI Pre-requisites
  aiFeaturesEnabled: true

• If you used a different database name from the recommended aiproxy default, you need to set the following value:

externalPostgresql:
  ## [... existing config...] 
  ## llmproxy database for AI functionalties
  aiProxyDatabaseName: "<aiproxy-custom-database-name>"