# Configure CARTO AI Prerequisites (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.

{% hint style="info" %}
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 [AI specific requirements](https://docs.carto.com/key-concepts/deployment-requirements#network-egress-requirements) section in Deployment Requirements.
{% endhint %}

{% hint style="warning" %}
Ensure your PostgreSQL password does not contain URI-special characters (`@`, `#`, `%`, etc.), as the AI Proxy builds database connection URLs internally. See [Deployment Requirements](https://docs.carto.com/key-concepts/deployment-requirements#external-databases) for details.
{% endhint %}

### 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](mailto:support@carto.com) to plan the migration to an external database.

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

```bash
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:

```sql
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.

```bash
kubectl cluster-info kubectl config current-context
```

* **List namespaces** to find your deployment:

```bash
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**:

```bash
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:

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

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

```sql
GRANT ALL PRIVILEGES ON DATABASE aiproxy TO <carto_user>;
ALTER DATABASE aiproxy OWNER TO <carto_user>;
```

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

{% hint style="info" %}
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.
{% endhint %}

## 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:

```yaml
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:

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