Быстрый старт

Voxagent поставляется бандлом — docker-compose.yml и эталонный .env.example — прямо с этого сайта документации. Образы лежат в приватном container registry registry.nodul.ru — доступ выдаётся по read-only токену (см. ниже).

1. Скачать бандл

mkdir Voxagent && cd Voxagent
curl -O https://docs.voxagent.ru/cdn/docker-compose.yml
curl -O https://docs.voxagent.ru/cdn/.env.example
mkdir -p env-gen caddy
curl -o env-gen/generate.sh https://docs.voxagent.ru/cdn/env-gen/generate.sh
curl -o caddy/Caddyfile https://docs.voxagent.ru/cdn/caddy/Caddyfile

• docker-compose.yml — полный стек сервисов (включает одноразовый сервис postgres-init, который создаёт дополнительные БД/пользователей после того как Postgres становится healthy)
• .env.example — эталонные переменные окружения
• env-gen/generate.sh — скрипт one-shot контейнера который генерирует готовый .env под ваш PUBLIC_HOST (см. шаги 4b и 4c)
• caddy/Caddyfile — конфиг Caddy reverse-proxy для опционального TLS-режима (используется только в 4c)

2. Запросить токен для реестра

Образы из registry.nodul.ru/voxagent/nodevoice/* требуют read-only токен. Токены выдаются каждому клиенту по запросу — напишите нам на help@mail.voxagent.ru, и мы пришлём токен.

После этого залогиньтесь на хосте — docker сам спросит логин и пароль:

docker login registry.nodul.ru/voxagent/nodevoice

3. Настроить

cp .env.example .env

Базовый .env.example уже содержит всё необходимое для локального запуска — можно оставить как есть и поднимать стек. Ключи LLM/STT/TTS-провайдеров, SMTP для Keycloak, биллинг, телефония и прочие интеграции — опциональны и нужны только для соответствующего функционала.

Полный референс переменных — в Конфигурации.

4. Запустить стек

Подтяните актуальные образы, чтобы не использовать устаревший :latest, закешированный при прошлом docker login:

DOCKER_DEFAULT_PLATFORM=linux/amd64 docker compose pull

Дальше — три сценария запуска. Выберите тот, который соответствует вашей инфраструктуре.

4a. Локальная разработка (по умолчанию)

Сценарий: Compose запущен на той же машине, с которой вы открываете приложение в браузере. Стек работает «из коробки» — никаких дополнительных настроек не требуется.

DOCKER_DEFAULT_PLATFORM=linux/amd64 docker compose up -d

Приложение будет доступно по адресу http://localhost:4200.

4b. Удалённый хост, доступ по IP

Сценарий: Compose запущен на удалённой машине (cloud-инстанс, on-premise сервер, машина в локальной сети), а вы открываете приложение в браузере с другого устройства.

В этой конфигурации браузер по умолчанию обращается к localhost своего устройства, а не к удалённому хосту. Чтобы публичные URL стека указывали на правильный адрес, необходимо перегенерировать файл .env с указанием адреса удалённого хоста:

# 1. На удалённом хосте — определите его IP-адрес:
curl -4 https://ifconfig.me           # публичный IP (cloud-инстансы)
hostname -I | awk '{print $1}'        # адрес в локальной сети (Linux)

# 2. Сгенерируйте .env с указанием этого адреса:
DOCKER_DEFAULT_PLATFORM=linux/amd64 PUBLIC_HOST=10.0.0.5 \
    docker compose run --rm env-gen

# 3. Запустите стек:
DOCKER_DEFAULT_PLATFORM=linux/amd64 docker compose up -d

env-gen — служебный одноразовый контейнер, который генерирует .env из шаблона .env.example. При обычном docker compose up он не запускается (находится за профилем tools) — вызывается только явной командой.

4c. Удалённый хост, доступ по доменному имени с TLS

Сценарий: стек обслуживается через настоящий домен с HTTPS, например https://app.dev.voxagent.ru, https://api.dev.voxagent.ru и т. д.

Настройка DNS

Все поддомены должны указывать на один и тот же IP — публичный адрес вашего хоста. Маршрутизацию между сервисами выполняет Caddy внутри стека. Доступны два варианта DNS-конфигурации.

Вариант A. Wildcard-запись (рекомендуется)

Вариант B. Отдельные A-записи для каждого поддомена

После создания записей дождитесь распространения DNS (обычно 5-30 минут). Проверить можно командой dig +short app.dev.voxagent.ru — должен вернуться указанный IP-адрес.

Конфигурация TLS

Caddy поддерживает два режима выпуска сертификатов:

• Let's Encrypt — публично-доверенные сертификаты, без предупреждений в браузере. Используется по умолчанию, если PUBLIC_HOST указан как реальный домен. Требует, чтобы порт 80 хоста был доступен из интернета (для HTTP-01 challenge).
• Локальный CA Caddy — Caddy выпускает собственный root CA и сертификаты от него. Используется автоматически для PUBLIC_HOST=localhost. На каждом устройстве, с которого открывается приложение, root CA необходимо добавить в системное хранилище доверенных сертификатов командой docker compose exec caddy caddy trust (выполняется в контейнере; для хост-системы потребуется извлечь и установить сертификат вручную).

Запуск стека

# 1. Сгенерируйте .env (env-gen автоматически переключит Caddy на Let's
#    Encrypt при указании реального домена):
DOCKER_DEFAULT_PLATFORM=linux/amd64 PUBLIC_HOST=dev.voxagent.ru PUBLIC_MODE=tls \
    CADDY_LE_EMAIL=admin@dev.voxagent.ru \
    docker compose run --rm env-gen

# 2. Запустите стек с профилем tls (включает Caddy):
DOCKER_DEFAULT_PLATFORM=linux/amd64 COMPOSE_PROFILES=tls docker compose up -d

Параметр CADDY_LE_EMAIL — email-адрес, на который Let's Encrypt будет присылать уведомления об истечении срока сертификатов. Если он не задан, env-gen использует значение admin@${PUBLIC_HOST}.

После запуска приложение доступно по адресам: https://app.dev.voxagent.ru, https://identity.dev.voxagent.ru, https://api.dev.voxagent.ru и т. д.

Полный процесс выпуска сертификатов для всех поддоменов занимает 5-10 минут на первом запуске. За прогрессом можно следить в логах: docker compose logs -f caddy.

Первый запуск занимает несколько минут — Postgres инициализируется, Keycloak импортирует realm, Lago накатывает миграции и сидит биллинг-организацию.

5. Дождаться angular-client

Проверить статус сервисов:

docker compose ps -a --format "table {{.Service}}\t{{.Status}}\t{{.Ports}}"

Как только строка angular-client покажет Up ... (healthy) — приложение готово, открывайте http://localhost:4200.

6. Создать пользователя

На странице входа нажмите Регистрация и создайте учётную запись.

В поставке для docker compose подтверждение email по умолчанию отключено (KEYCLOAK_VERIFY_EMAIL=false), регистрация моментальная.

Включить подтверждение email

Если хотите, чтобы пользователи подтверждали почту перед первым входом, в .env:

1. Включите флаг:

   KEYCLOAK_VERIFY_EMAIL=true

2. Заполните SMTP-реквизиты Keycloak (с них уходят письма верификации и сброса пароля):

   KEYCLOAK_SMTP_HOST=smtp.example.com
   KEYCLOAK_SMTP_PORT=465
   KEYCLOAK_SMTP_FROM=no-reply@example.com
   KEYCLOAK_SMTP_USER=<smtp-логин>
   KEYCLOAK_SMTP_PASSWORD=<smtp-пароль>
   KEYCLOAK_SMTP_SSL=true       # 465
   KEYCLOAK_SMTP_STARTTLS=false # переключите на true для порта 587

3. Перезапустите Keycloak, чтобы применить:

   docker compose up -d --force-recreate keycloak

Другие точки входа

Когда стек полностью поднялся:

Порты настраиваются в .env в секции HOST PORTS — меняйте любой, если на вашей машине он уже занят.

Что дальше

• Требования — подобрать хост под ожидаемую нагрузку.
• Конфигурация — полный референс переменных.
• Установка — другие варианты развёртывания (managed, Kubernetes).