# Configure CARTO AI Prerequisites (Kots)

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

{% hint style="info" %}
For Single VM Deployments check the hardware requirements when enabling AI Features [here](https://docs.carto.com/carto-for-developers/key-concepts/architecture).
{% endhint %}

## 1. Requirements

Before modifying the KOTS 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. 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.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.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-6d09fc7124fc79f3d6e4dc85e048cb04fe97ac9b%2Fimage%20(740).png?alt=media" alt=""><figcaption></figcaption></figure>

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

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

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

{% 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 Configuration

Once the infrastructure prerequisites are met, you must enable the CARTO AI Pre-requisites in the Admin Console config section.

### 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 :heavy\_check\_mark:**.**
* 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`).

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-cfe3527aa4968b27de6a0b6de8d3f2e099d47584%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

* Go to the bottom of the page and click on **Save Config**.
* Click on **Go to updated version**.

## 3. Deploy updated version

Saving the configuration generates a **new version** sequence that **must be deployed to apply the changes**.

### 3.1 Initiate Deployment

* Go to the **Version history** tab.
* Locate the new version Available.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-adfcb215d914954aa88cf33af51ca77e7f4e1f10%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-23b15c5f79831c83a4741d6b02e46c7b30d2d10f%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

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