Требования

Прочитайте эту страницу до того, как запрашивать машину и домен: половина проблем при установке — это несовпадение подсетей, отсутствующие сертификаты для Elasticsearch или диск, рассчитанный без учёта роста ClickHouse. Ниже — только то, что зафиксировано в документах и конфигурации продукта, и отдельно показано, где точной цифры нет и как её оценить самостоятельно.

Операционная система и инструменты

Требование	Значение
Операционная система	Linux, архитектура amd64 или arm64
Docker Engine	24 или новее
Docker Compose	v2, проверяется командой docker compose version
Оболочка	bash, а также awk, grep, stat — их использует предварительная проверка
Генерация секретов	openssl на машине оператора
Роли PostgreSQL	клиент psql, если вы применяете роли для каждого сервиса

Для варианта с Kubernetes нужен кластер и helm. Чарт объявлен как apiVersion: v2 и не задаёт ограничения по версии Kubernetes, а документы продукта не называют минимальные версии кластера и Helm. Ориентируйтесь на версии, которые поддерживает ваш дистрибутив Kubernetes, и проверьте установку на тестовом кластере: чарт использует только Deployment, Job, DaemonSet, Service, ConfigMap, Secret, PersistentVolumeClaim, Role/RoleBinding и NetworkPolicy.

Процессор, память и диск

Документы продукта называют одну точку — стартовую конфигурацию:

Ресурс	Стартовое значение
Процессор	4 vCPU
Память	8 ГБ
Диск	50 ГБ

Что важно знать про эти 8 ГБ: они относятся ко всей установке, а не к приложению. Compose в on-prem всегда поднимает Elasticsearch, у которого размер heap по умолчанию задан как -Xms1g -Xmx1g, плюс Kibana, Prometheus, Grafana, Jaeger и четыре экспортёра. То есть 8 ГБ — это нижняя граница, при которой всё перечисленное вообще запускается.

От чего зависит реальный размер

Что растёт	От чего
ClickHouse	поток событий и срок хранения — 25 месяцев для событий, 90 дней для записей сессий
PostgreSQL	число пользователей, проектов, отчётов, импортов и записей журнала аудита
Тома JetStream	пиковый поток событий и отставание записи; транспортное хранение — до 48 часов
Prometheus	срок хранения метрик, по умолчанию 15 дней
Elasticsearch	объём логов контейнеров и срок их хранения, по умолчанию 30 дней
Каталог загрузок импорта	размер файлов, которые вы загружаете для исторического импорта

Как оценить размер под свою нагрузку

1. Возьмите фактический поток событий: сколько событий в сутки вы отправляете сейчас или планируете отправлять, и средний размер свойств у события.
2. Поднимите установку на стартовой конфигурации и подайте на неё поток, похожий на боевой, хотя бы несколько часов.
3. Снимите с Prometheus фактический прирост: размер тома ClickHouse на событие, отставание записи, использование процессора и памяти каждым контейнером. Метрики для этого уже настроены — см. Мониторинг.
4. Умножьте измеренный прирост ClickHouse на срок хранения и добавьте запас на слияния частей и мутации: во время удаления данных субъекта и очистки по сроку хранения ClickHouse временно занимает больше места.
5. Заложите отдельный запас под резервные копии, если храните их не в S3, а на том же хосте — так делать не рекомендуется, но если делаете, считайте это отдельной статьёй расхода.

Алерты по свободному месту в комплекте уже есть: они срабатывают на предупреждающем и критическом порогах и защищают от самой неприятной аварии — остановки ClickHouse из-за заполненного диска.

Сеть и порты

Что публикуется на хост

Только Caddy и только два порта:

Порт	Зачем
80	HTTP; нужен для выпуска сертификата и перенаправления на HTTPS
443	весь рабочий трафик: приём событий, API, интерфейс

Больше на хост ничего не публикуется. Ни Prometheus, ни Grafana, ни Kibana, ни базы данных, ни один из портов метрик приложения не имеют секции публикации портов: доступ к ним — только через контролируемый port-forward или VPN.

Внутренние порты

Внутри compose сервисы обращаются друг к другу по именам и портам, которые никуда не публикуются:

Порт	Сервис	Назначение
8080	query-api	HTTP API /api/v1 и /healthz
8081	ingest-api	приём событий по /v1/*, ассеты трекера, /healthz
9090	каждый контейнер приложения	/metrics для Prometheus
5432	postgres	PostgreSQL
8123, 9000	clickhouse	HTTP-интерфейс и нативный протокол
9363	clickhouse	собственный эндпоинт метрик ClickHouse
6379	redis	Redis
4222	nats	клиентские подключения
8222	nats	служебный интерфейс: состояние, потоки, консьюмеры
9200	elasticsearch	HTTPS с обязательной аутентификацией
4318	jaeger	приём трейсов по OTLP через HTTP
9093	alertmanager	приём алертов от Prometheus
9100, 9187, 9121, 7777	экспортёры	метрики хоста, PostgreSQL, Redis и NATS
5066	filebeat	статистика доставки логов

Остальные сервисы наблюдаемости слушают порты по умолчанию своих образов.

Сети и подсети

Compose создаёт четыре сети. Две из них — внутренние: у них нет маршрута ни на хост, ни наружу.

Сеть	Подсеть по умолчанию	Особенность
edge	172.31.255.0/29	только Caddy; на этой сети у него статический адрес
app	172.31.253.0/24	приложение; исходящий трафик разрешён намеренно — для SMTP, webhook’ов и телеметрии по согласию
data	172.31.254.0/24	внутренняя: PostgreSQL, ClickHouse, Redis, NATS
observability	172.31.252.0/24	внутренняя: метрики, логи, трейсы

Исходящий трафик

Куда	Обязательно	Зачем
Реестр образов	да	загрузка образов, зафиксированных по digest; либо ваше зеркало
Удостоверяющий центр TLS	при реальном домене	автоматический выпуск и продление сертификата
Ваш SMTP-сервер	нет	письма подтверждения адреса, восстановления пароля и приглашений
Хранилище, совместимое с S3	нет	резервные копии; используйте HTTPS-эндпоинт
Ваши приёмники webhook’ов	нет	канал доставки алертов
Эндпоинт телеметрии ActionPulse	нет	выключен по умолчанию, включается только явным согласием

Если у установки нет выхода в интернет, заранее решите два вопроса: откуда берутся образы (зеркало реестра) и откуда берётся сертификат — при домене localhost Caddy выпустит самоподписанный сертификат, а для реального домена без выхода к удостоверяющему центру автоматический выпуск не сработает.

Хранилища

Все данные лежат в именованных томах Docker, то есть на диске хоста в каталоге данных Docker. Планируйте место именно там, а не в каталоге, куда распакован комплект.

Том	Что в нём
pg-data	PostgreSQL
ch-data	ClickHouse: события и аналитические таблицы
nats-data	хранилище JetStream
redis-data	Redis
import-uploads	загруженные файлы исторического импорта; том общий для query-api и worker
caddy-data, caddy-config	сертификаты и состояние прокси
prometheus-data, alertmanager-data, grafana-data	метрики, состояние алертов, настройки панелей
es-data, kibana-data, filebeat-data	логи, состояние Kibana, смещения чтения логов
backup-state, backup-metrics	состояние раннера бэкапов и файл метрик для экспортёра

В Kubernetes каталог загрузок импорта — отдельная история: query-api и worker работают с ним одновременно, поэтому том обязан поддерживать одновременное монтирование на запись с нескольких узлов. Тома для баз данных в этом варианте предоставляете вы.

Предварительная проверка окружения

В корне комплекта лежит preflight.sh — закрытая проверка конфигурации, которая запускается до первого старта:

./preflight.sh .env

Успех выглядит так:

preflight: environment, exact image refs and external secret files passed

Отдельно можно проверить только контракты прав доступа к Redis и NATS, не затрагивая остальное:

./preflight.sh --validate-acl-contracts secrets/redis-users.acl secrets/nats-server.conf

Что именно проверяется:

• Сам файл. .env должен быть обычным файлом, а не символической ссылкой, с нулевыми правами для группы и остальных (то есть 0600), и содержать ровно одну запись на каждый ключ. Дубликат ключа — отказ: иначе значение молча переопределялось бы последней строкой.
• Секреты. Двенадцать обязательных секретов должны быть длиной не менее 24 символов, без пробелов и не совпадать с известными заглушками вида change_me, example, placeholder, password, secret, dev, test. Ключ шифрования второго фактора, если он задан, — не короче 32 символов.
• Первый владелец. BOOTSTRAP_EMAIL и BOOTSTRAP_PASSWORD должны быть либо оба заданы, либо оба пусты. Пароль — не менее 16 символов, адрес — в каноническом нижнем регистре и не на демонстрационном домене.
• Образы. Все семь ссылок на образы обязаны иметь вид tag@sha256:… с полным digest’ом. Ссылка только по тегу релизом не считается и отклоняется.
• Подключения. Адреса NATS и Redis должны быть аутентифицированными, с паролем не короче 16 символов. Если задан отдельный адрес для конкретного сервиса, он обязан использовать именно его учётную запись — опечатка иначе молча вернула бы сервис на общий аккаунт. Привилегированные служебные учётные записи NATS запрещено выдавать долгоживущим сервисам.
• Подключения к ClickHouse. Каждое подключение обязано использовать предназначенную ему роль — отдельную для миграций, записи, чтения и SQL-консоли — и внутреннее имя хоста.
• Подписи резервных копий. Ключ подписи манифеста и список публичных ключей обязательны всегда, даже если профиль бэкапов вы никогда не включите. Режим без подписи манифеста отклоняется, а режим подсчёта хешей ClickHouse разрешён только полный.
• Файлы вне .env. ACL Redis и конфигурация NATS должны быть обычными файлами с правами 0600; сертификаты и приватные ключи Elasticsearch и Kibana должны существовать, а приватные ключи — быть с правами 0600.
• Содержимое ACL и конфигурации. В ACL Redis анонимный пользователь по умолчанию должен быть выключен и должен быть хотя бы один включённый пользователь с паролем и без разрешения входа без пароля. В конфигурации NATS должен быть включён JetStream с ожидаемым каталогом хранения, служебный интерфейс на внутреннем порту и блок авторизации с пользователем и паролем. Дополнительно проверяются права наименьшего доступа: сервис приёма событий получает маркер квоты только на чтение и может лишь читать описание потоков, но не создавать и не изменять их.

После preflight.sh полезно прогнать разбор самого compose — он найдёт отсутствующие обязательные переменные:

docker compose -f docker-compose.onprem.yml --env-file .env config --quiet

Молчание — это успех.

Что подготовить заранее

Домен и сертификаты

• Доменное имя и запись DNS на адрес хоста. Домен задаётся одной переменной, от него же зависят публичные адреса установки.
• Доступность портов 80 и 443 с той стороны, откуда придёт удостоверяющий центр, — иначе автоматический выпуск сертификата не завершится.
• Публичные адреса установки обязаны быть на https, когда домен настоящий: от этого зависит признак Secure у cookie аутентификации.
• Собственный сертификат для внешнего домена в поставляемой конфигурации Caddy не предусмотрен: в ней нет ни директивы для своего сертификата, ни указания удостоверяющего центра, ни адреса для учётной записи ACME. Используется автоматический выпуск по домену. Если вам нужен свой сертификат — терминируйте TLS на собственном прокси перед установкой.
• Отдельно: центр сертификации, сертификат и приватный ключ для Elasticsearch и такая же пара для Kibana. Это обязательные файлы — без них проверка не пройдёт и стек не поднимется, даже если логи вам не нужны.

Файлы вне .env

Файл	Обязателен	Что это
ACL Redis	да	список пользователей Redis с правами; шаблон в комплекте заведомо нерабочий
Конфигурация NATS	да	учётные записи JetStream; шаблон в комплекте заведомо нерабочий
Центр сертификации Elasticsearch	да	проверка TLS-соединений со стеком логов
Сертификат и ключ Elasticsearch	да	HTTPS у Elasticsearch
Сертификат и ключ Kibana	да	HTTPS у Kibana
База GeoIP	нет	определение страны по адресу; в комплект не входит, приносите свою

Все перечисленные файлы живут вне репозитория и вне образов, монтируются как файловые секреты, а приватные ключи должны иметь права 0600.

Секретные значения

Значения секретов нигде не публикуются и не приходят в комплекте: шаблоны намеренно содержат заглушки, которые проверка отклоняет. Сгенерируйте своё независимое значение для каждого пункта — по одному на каждый, не переиспользуя одно и то же:

Переменная	Обязательна	Назначение
JWT_SECRET	да	подпись токенов доступа
PG_PASSWORD	да	пароль основной учётной записи PostgreSQL
CH_DEFAULT_PASSWORD	да	служебная учётная запись ClickHouse; должна совпадать со значением, которое получает контейнер ClickHouse
CH_MIGRATE_PASSWORD	да	роль миграций ClickHouse
CH_WRITE_PASSWORD	да	роль записи ClickHouse
CH_READ_PASSWORD	да	роль чтения ClickHouse
CH_BACKUP_PASSWORD	да	роль резервного копирования ClickHouse
CH_CONSOLE_PASSWORD	да	роль SQL-консоли, создаётся миграцией
GRAFANA_ADMIN_PASSWORD	да	вход в Grafana
ELASTIC_PASSWORD	да	учётная запись Elasticsearch
KIBANA_SYSTEM_PASSWORD	да	служебная учётная запись Kibana
ELASTICSEARCH_FILEBEAT_PASSWORD	да	учётная запись доставки логов
IMPORT_ENC_KEY	да	шифрование строк подключения для исторического импорта
IMPORT_HMAC_CURRENT_SECRET	да	подпись передачи данных импорта
IMPORT_FENCE_HMAC_CURRENT_SECRET	да	подпись маркеров устойчивости импорта
IMPORT_PRIVACY_HMAC_CURRENT_SECRET	да	устойчивые токены субъектов для удаления данных
ALERT_WEBHOOK_ENC_KEY	да	шифрование адресов webhook’ов; ровно 32 байта до кодирования в base64
BACKUP_MANIFEST_SIGNING_KEY	да	подпись манифеста резервной копии
BACKUP_MANIFEST_PUBLIC_KEYS	да	список публичных ключей для проверки манифеста
BOOTSTRAP_PASSWORD	до первого входа	пароль первого владельца; после создания владельца очищается
MFA_ENCRYPTION_KEY	нет	отдельный ключ для второго фактора; пустое значение использует JWT_SECRET
SMTP_PASS	нет	пароль SMTP, если сервер требует аутентификацию

Публичный ключ поставщика для проверки лицензии (LICENSE_PUBKEY) — тоже обязательное значение, но это не секрет: его выдаёт поставщик вместе с лицензией. Сам ключ лицензии в .env не кладётся — он загружается через API уже работающей установки, см. Лицензию.

Лицензия и доступ к поставке

• Файл лицензии от поставщика и его публичный ключ проверки.
• Доступ к аутентифицированному каналу поставки: сам архив, его контрольная сумма и подписанный release-манифест. Проверяйте и сумму, и манифест до распаковки.
• Прочитайте список изменений выпуска: обновление существующей установки — это не та же процедура, что установка на чистую машину, и для хранилищ требуется поэтапный маршрут с промежуточными проверками.

Что проверить перед первым запуском

• Хост на Linux, docker compose version показывает v2, а docker version — движок 24 или новее.
• Подсети edge, app, data, observability не пересекаются с адресацией хоста и VPN, а список доверенных прокси соответствует адресу Caddy.
• Порты 80 и 443 на хосте свободны, и никакой другой веб-сервер их не занимает.
• Домен разрешается в адрес хоста, а порты 80/443 достижимы снаружи.
• Все семь обязательных файлов вне .env на месте (ACL Redis, конфигурация NATS, центр сертификации, две пары сертификат-ключ), приватные ключи с правами 0600.
• .env имеет права 0600 и содержит ровно одну запись на ключ.
• ./preflight.sh .env завершается успешной строкой.
• docker compose -f docker-compose.onprem.yml --env-file .env config --quiet ничего не печатает.

Дальше — Развёртывание в Docker Compose.