Установка через Docker Compose вручную

Этот способ — для тех, у кого уже есть свой обратный прокси с HTTPS и свои правила для Docker-хостов. Если сервер чистый, проще install.sh: он делает те же шаги сам и умеет обновлять с откатом.

Нужен Docker с Docker Compose v2.24 или новее.

1. Создать файлы

Создайте каталог (например, /opt/kvalli) и положите в него docker-compose.yml:

yaml

services:
  app:
    image: ${KVALLI_IMAGE}
    restart: unless-stopped
    env_file: .env
    environment:
      - NODE_ENV=production
      - PORT=3000
      - DATABASE_URL=postgres://kvalli:${POSTGRES_PASSWORD}@postgres:5432/kvalli_db
      - KVALLI_AUTH_MODE=enforced
      - KVALLI_DATA_DIR=/app/data
      - KVALLI_QA_AGENTS_DIR=/app/.qa-agents
    ports:
      - "127.0.0.1:3000:3000"   # к приложению ходит только ваш прокси
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - kvalli_data:/app/data
      - kvalli_qa_agents:/app/.qa-agents
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: kvalli
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: kvalli_db
    volumes:
      - kvalli_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kvalli -d kvalli_db"]
      interval: 5s
      timeout: 5s
      retries: 10
volumes:
  kvalli_pgdata:
  kvalli_data:
  kvalli_qa_agents:

Рядом — .env. Пароль базы должен состоять только из букв, цифр и . _ ~ -: он подставляется в строку подключения как есть. openssl rand -hex 24 подходит.

Заполните в .env:

Переменная	Что указать
`POSTGRES_PASSWORD`	Пароль встроенного PostgreSQL
`ENCRYPTION_KEY`, `JWT_SECRET`	Случайные строки: `openssl rand -hex 32`
`KVALLI_IMAGE`	`ghcr.io/kvalli-ai/kvalli:2.3.0` или `ghcr.io/kvalli-ai/kvalli-starter:2.3.0`
`KVALLI_ADMIN_EMAIL`, `KVALLI_ADMIN_PASSWORD`	Первый администратор, пароль от 12 символов. Нужны только для первого запуска
`KVALLI_LICENSE`	Лицензионный ключ, если он есть

Остальные настройки — в разделе Переменные окружения: .env целиком передаётся в контейнер.

Сохраните ENCRYPTION_KEY

Учётные данные интеграций хранятся в базе зашифрованными этим ключом. Без него восстановленная база бесполезна: держите ключ вместе с резервными копиями.

2. Запустить

bash

docker login ghcr.io       # для полной редакции: токен на чтение, выданный с ключом
docker compose pull
docker compose up -d

При запуске приложение применяет миграции базы и, если пользователей ещё нет, создаёт администратора из KVALLI_ADMIN_EMAIL и KVALLI_ADMIN_PASSWORD. Затем удалите KVALLI_ADMIN_PASSWORD из .env.

3. Поставить за HTTPS

Поставьте Kvalli за ваш обратный прокси с HTTPS: прокси ходит на 127.0.0.1:3000, пользователи открывают https://<ваш адрес>/app. В production cookie сеанса помечены Secure, поэтому по обычному HTTP вход не сохранится. Задайте в .env:

KVALLI_PUBLIC_URL — публичный адрес, например https://kvalli.company.internal;
ALLOWED_ORIGINS — добавьте туда тот же адрес;
TRUST_PROXY_HOPS=1 — если перед Kvalli один прокси.

Прокси должен пропускать загрузки до 100 МБ, долгие ответы (до часа) и не буферизовать потоковые ответы: по ним приходит прогресс заданий агентов.

Где хранятся данные

Том	Что в нём
`kvalli_pgdata`	PostgreSQL: все записи, включая настройки интеграций и зашифрованные учётные данные
`kvalli_data`	Байты вложений и доказательств прогонов, кэш репозиториев, идентификатор установки для телеметрии
`kvalli_qa_agents`	Старые файлы пользовательских агентов, которые ранние версии писали на диск. На текущей установке обычно пуст

Встроенные навыки лежат не в томе, а в самом образе (/app/builtin-skills), поэтому каждое обновление приносит их новую версию.

Обновление и резервные копии

При ручной установке и то и другое — ваша забота: см. Обновления и Резервные копии.

Установка через Docker Compose вручную ​

1. Создать файлы ​

2. Запустить ​

3. Поставить за HTTPS ​

Где хранятся данные ​

Обновление и резервные копии ​