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

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.

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

Backend setup

The backend configuration 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); 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:

CREATE DATABASE flip_ai_core OWNER flip;

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

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

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.