Установка и развёртывание программного обеспечения «Rowux»

Документ описывает порядок установки и запуска ПО «Rowux». Предназначен для системного администратора / инженера по эксплуатации.

#1. Требования к среде

Минимально необходимое программное обеспечение на сервере развёртывания:

• Операционная система семейства Linux (поддерживаются также macOS для целей разработки).
• Docker Engine и Docker Compose (v2).
• Доступ к сети для первичной загрузки образов и, при необходимости, к поставщикам языковых моделей.

Рекомендуемая минимальная конфигурация сервера для промышленной эксплуатации:

При изолированном исполнении кода аналитического агента на отдельной виртуальной машине требуется дополнительный вычислительный узел. При локальном размещении языковых моделей требования к ресурсам (в первую очередь к видеопамяти) определяются выбранной моделью.

#2. Состав дистрибутива

Дистрибутив представляет собой репозиторий исходного кода, содержащий:

• файл оркестрации docker-compose.yml (и наложение docker-compose.egress.yml для промышленного контура с закрытым исходящим трафиком);
• исходный код собственных сервисов (ui, backend, ghost-writer-backend, ghost-writer-ui, analytics-agent, pii-guard, landing);
• исходный код доработанных компонентов (open-webui, langflow);
• конфигурационные файлы среды-образцы (.env.local — для локального запуска, .env.rowux-ru, .env.rowux-online — для промышленных сред);
• файл описания области аутентификации (realm) для системы единого входа;
• вспомогательные сценарии (scripts/) и документацию (docs/).

#3. Конфигурирование

Перед запуском необходимо подготовить файл переменных окружения .env. В поставку входят готовые шаблоны под разные среды развёртывания:

Выбранный шаблон копируется в .env:

cp .env.local .env      # для локального запуска

Ключевые группы переменных окружения:

• Домен и адреса сервисов — DOMAIN, публичные и внутренние URL подсистем.
• Учётные записи администраторов подсистем (чат-интерфейс, конструктор сценариев, система единого входа, база данных).
• Доступ к языковым моделям — базовые адреса и ключи поставщиков (в том числе российских), настройки шлюза моделей.
• Хранилища — параметры объектного (S3-совместимого) и векторного хранилищ.
• Параметры аналитического агента — модели, подключения к базам данных (только на чтение), настройки песочницы.
• Список разрешённых источников (ROWUX_UI_URLS) для межсервисного доступа.

Секреты (пароли, ключи API) задаются в .env и не входят в состав исходного кода. В промышленных средах рекомендуется задавать их средствами менеджера секретов среды развёртывания.

Для промышленной среды с закрытым исходящим трафиком в .env дополнительно указывается наложение файла оркестрации:

COMPOSE_FILE=docker-compose.yml:docker-compose.egress.yml

#4. Запуск

Полный запуск всего комплекса выполняется из корневого каталога проекта:

docker compose down -v      # (при необходимости) полная очистка предыдущего состояния
docker compose up -d        # сборка образов и запуск всех сервисов в фоне

После выполнения команды все подсистемы поднимаются и связываются между собой автоматически. Сервисы инициализации (создание учётных записей хранилища, загрузка стартовых сценариев и моделей, инициализация подсистемы мониторинга) отрабатывают автоматически при первом старте.

#5. Первичная настройка после запуска

1. Создание пользователей в системе единого входа (Keycloak). В области аутентификации (realm) rowux учётные записи из коробки отсутствуют — их необходимо создать через административную консоль системы единого входа.
2. Проверка доступности. Подсистемы становятся доступны по адресам, заданным в .env. При локальном запуске основные подсистемы доступны на портах: портал — 3000, чат-интерфейс — 8091, конструктор сценариев — 7860, система единого входа — 8484, сервер-обвязка — 8092, подсистема мониторинга — 9090/3001. В промышленной среде доступ публикуется через пограничный маршрутизатор трафика (Traefik) по протоколу HTTPS (порты 80/443).

При локальном запуске, если административная консоль системы единого входа сообщает об обязательности HTTPS, требование можно отключить для локальной среды штатными командами административного клиента системы единого входа:

docker exec -it keycloak /opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 --realm master --user admin --password admin
docker exec -it keycloak /opt/keycloak/bin/kcadm.sh update realms/master \
  -s sslRequired=NONE

Это требуется не на всех окружениях; на части машин локальный запуск по HTTP работает без дополнительных действий.

#6. Обновление и остановка

• Обновление: получить новую версию исходного кода, затем повторить docker compose up -d --build — будут пересобраны и перезапущены только изменённые сервисы. Миграции схем баз данных выполняются автоматически при старте соответствующих сервисов.
• Остановка: docker compose down (с сохранением данных) либо docker compose down -v (с удалением томов данных).

#7. Автоматизированное развёртывание (CI/CD)

Для промышленных сред поставляется конфигурация непрерывного развёртывания (.gitlab-ci.yml): по событию в репозитории код доставляется на целевой сервер, подставляется соответствующий среде файл .env, при необходимости собирается образ песочницы аналитического агента и выполняется docker compose up -d --build. Порядок промышленного развёртывания, в том числе изоляции песочницы, приведён в docs/sandbox-rollout-runbook.md.