---
url: https://flip-chart.ru/developers/en/on-premise/config/ai-core.md
description: >-
  Configuration of flip on-premise ai-core, the local AI core: connection to the
  flip cloud, the flip_ai_core database, the backend token, config.yaml fields
  and environment variables.
---

# ai-core configuration

 Download the example configuration file 

ai-core is the local AI core of flip on-premise. The service registers the installation in the flip cloud and proxies AI feature requests (image generation, background removal, AI text) to the cloud core at `https://ai.flip-chart.ru`. The installation key is stored encrypted in the ai-core database. ai-core accepts incoming requests only from the backend; it does not need to be published via the reverse proxy.

The component is optional: without ai-core the application works, but AI features are unavailable (see [Disabling](#disabling)).

The configuration file is mounted into the container at `/flip/cfg/config.yml`. The database connection string is set with the `POSTGRES_DSN` environment variable: migrations are applied with it when the container starts, and the container does not start without it.

::: warning Network access
Outbound HTTPS access (port 443) to `ai.flip-chart.ru` is required. The `HTTP_PROXY` and `HTTPS_PROXY` environment variables are not used; the proxy is set in `Upstream.ProxyURL` (see [Additional settings](#additional-settings)).
:::

::: warning Backend setup
The [backend configuration](/en/on-premise/config/backend#ai) sets the ai-core address (`AI.LocalCore.BaseURL`) and the access token (`AI.LocalCore.Token`), which matches `Auth.Local.Token`. AI features also require file-handlers to be enabled in the backend (`FileHandlerServiceConfig`) and S3 storage.
:::

## Environment variables

| Variable | Description |
|---|---|
| `POSTGRES_DSN` | Required. Connection string of the `flip_ai_core` database (secret). In Docker Compose it is set in `.env` (`AI_CORE_POSTGRES_DSN`); in Kubernetes, with the `POSTGRES_DSN` key of the `ai-core-config` secret. |

Example: `postgres://flip:secret-passwd@flip-postgres:5432/flip_ai_core?sslmode=disable`. Special characters in the user name and password are encoded ([percent-encoding](https://www.postgresql.org/docs/15/libpq-connect.html#LIBPQ-CONNSTRING-URIS)); for a TLS connection, use `sslmode=require` or `sslmode=verify-full`.

The configuration file fields can also be set with environment variables: the field path in upper case, `.` → `_` (`Auth.Local.Token` → `AUTH_LOCAL_TOKEN`). An environment variable takes precedence over the file.

## Database

ai-core uses a separate `flip_ai_core` database on the same PostgreSQL server as the backend. Create the database before the first ai-core start:

```sql
CREATE DATABASE flip_ai_core OWNER flip;
```

`flip` is the application PostgreSQL user. In a Standalone installation (the `deploy/docker-compose` directory):

```bash
docker compose exec flip-postgres sh -c 'createdb -U "$POSTGRES_USER" -O "$POSTGRES_USER" flip_ai_core'
```

## Configuration fields

An unknown key in the file is a startup error.

### Auth.Local

* **Token**: Backend access token for ai-core (secret), at least 32 characters. Matches `AI.LocalCore.Token` in the backend configuration. Generate it with `openssl rand -hex 32`.
* **PreviousToken**: The previous token during [rotation](#token-rotation). Not set outside rotation.

### Postgres

Optional connection pool settings.

* **MaxOpenConns**, **MaxIdleConns**: Connection pool size. `0` means the driver default.\
  Example: `10`
* **ConnMaxLifetime**: Maximum connection lifetime. `0` means no limit.\
  Example: `30m`

## Additional settings

The log level, the proxy and the listener addresses are set in a separate optional file. Its path is set in the `ADJUSTABLE_CONFIG_FILE` environment variable. These settings are not set in `config.yml` or with environment variables. Without the file, the defaults apply.

```yaml
Logger:
  Level: info          # debug | info | warn | error
  Elastic: false       # ECS log format
Upstream:
  ProxyURL: ""         # proxy for requests to https://ai.flip-chart.ru, for example http://proxy.example.ru:3128
Server:
  PublicAddr: ":9100"
  MetricsAddr: ":9102"
  ShutdownTimeout: 10s
```

`Upstream.ProxyURL` is an absolute URL with the `http` or `https` scheme. When changing the ports in `Server`, also update `AI.LocalCore.BaseURL` in the backend and the container ports.

## Ports

| Port | Purpose |
|---|---|
| 9100 | API for the backend |
| 9102 | `/metrics`, `/healthz`, `/readyz` |

## Shutdown

On shutdown ai-core waits for the started generations to complete. The container stop timeout is at least 120 seconds: `stop_grace_period: 120s` in docker-compose, `terminationGracePeriodSeconds: 120` in the Helm chart.

## Token rotation

1. In the ai-core configuration, set the current token in `Auth.Local.PreviousToken` and the new one in `Auth.Local.Token`; restart ai-core.
2. Set the new token in `AI.LocalCore.Token` of the backend configuration; restart the backend.
3. Remove `Auth.Local.PreviousToken` from the ai-core configuration; restart ai-core.

## Disabling

* **Docker Compose**: remove the `flip-ai-core` service from `docker-compose.yaml` and the `AI` section from the backend configuration, then run `docker compose up -d --remove-orphans`.
* **Kubernetes**: set `ai-core.enabled: false` in `values.yaml`, remove the `AI` section from the backend configuration and run `helm upgrade`.