Configure CARTO AI prerequisites
For CARTO Self-Hosted
This guide provides instructions for enabling the necessary prerequisites to run CARTO AI features in a Self-Hosted environment. It covers configuration changes, deployment steps, and validation of the AI proxy resources.
For Single VM Deployments check the hardware requirements when enabling AI Features here.
1. Requirements
Before modifying the configuration, you must prepare your database and network environment.
If your deployment restricts outbound network traffic (e.g., via a firewall or proxy), make sure the required AI provider domains are whitelisted. See the egress requirements for the full list.
Ensure your PostgreSQL password does not contain URI-special characters (@, #, %, etc.), as the AI Proxy builds database connection URLs internally.
1.1. 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:
1.1.1 Identify the database user
You must identify the specific database user currently configured for your deployment to grant it permissions later.
Login to the KOTS Admin Console.
Navigate to the Config tab.
Locate the Metadata Database configuration section.
Note the value in the User field.
1.1.2 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.
1.2 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 in 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.
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:
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:
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
kubectlcli tool .Verify connection: check that you are in the correct cluster.
List namespaces to find your deployment:
Note the CARTO namespace
<namespace>.
1.3.2 Find your Helm Release
Make sure that you have
helmcli tool installed .Run the following Helm command to get the release name:
Note the CARTO release name
<release-name>(first column named "NAME").
1.3.3 Get the Metadata Database user name:
Based on the previous information about the release name:
1.4 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.
1.5 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 Configuration
Once the infrastructure prerequisites are met, you must enable the CARTO AI Pre-requisites.
2.1 Enable CARTO AI Pre-requisites
Navigate to the Config tab in the Admin Console.
Scroll down to the Advanced Config section.
Locate the CARTO AI Pre-requisites subsection. Check the box ✔️.
Go to the bottom of the page and click on Save Config.
Click on Go to updated version.
2.2 Optional: Setup a Custom Database name for AI Proxy
By default, the system expects the database name to be aiproxy. If you created a database with a different name in Step 1.1, you must specify it here.
In the same Advanced Config section, locate the AI Proxy Database name field.
Enter your custom database name (e.g.,
aiproxy_custom_database).
Go to the bottom of the page and click on Save Config.
Click on Go to updated version.
Add the following lines to your customizations.yaml file:
If you used a different database name from the recommended
aiproxydefault, you need to set the following value:
3. Deploy updated version
Saving the configuration generates a new version that must be deployed to apply the changes.
3.1 Initiate Deployment
Go to the Version history tab.
Locate the new version Available.
3.2 Preflight checks
KOTS will automatically run preflight checks to ensure connectivity and requirements are met.
Check that the Preflight checks ran correctly.
If you click on the View Preflight checks icon you'll be able to see all details
3.3 Deploy
Now that we enabled the new settings, and made sure that the Preflight Checks are healthy we can go ahead and deploy it to the cluster.
Click on the Deploy Icon, and then click on Yes, Deploy. b
Now the new CARTO version is being deployed with the AI Pre-requisites enabled!
3.4 Monitor deploy
Once you deployed the new version you must check that everything gets deployed sucessfully and that your application is healthy.
In the Dashboard section, click on Details.
You'll see that your Resources are updating:
Once the the upgrade finishes you will see all Resources in Ready state.
Apply the updated customizations.yaml using the standard Helm upgrade process for your CARTO Self-Hosted deployment. Verify that the AI proxy resources are created and running successfully in your cluster.
Last updated
Was this helpful?