25 KiB
container-run Specification
Purpose
Как стенд сервиса запускается и настраивается: compose с PostgreSQL,
Valkey, сервером S3, одноразовыми миграциями и bootstrap S3 и API
(make run_docker), публикация портов только на localhost,
конфигурация на старте, сохранность данных при рестарте стенда и явное
удаление учебных данных.
Requirements
Requirement: Запуск через compose
make run_docker SHALL собирать образ и поднимать стенд через
docker compose. В стенд входят:
- PostgreSQL и Valkey;
- сервер S3 (capability
object-storage); - брокер (capability
message-broker); - одноразовые сервисы миграций и bootstrap S3;
API_REPLICASреплик API (capabilityload-balancing);- уборщик незавершённых загрузок (capability
storage-consistency) — один долгоживущий процесс на образе API со своей командой; - relay (capability
job-outbox) — долгоживущий процесс на образе API со своей командой; - worker (capability
attachment-processing) — долгоживущий процесс на образе API со своей командой; - балансировщик (LB);
- OTel Collector, хранилища метрик, логов и трасс и Grafana (capability
observability).
Реплики API SHALL стартовать после готовности PostgreSQL и Valkey, успешных миграций и успешного bootstrap S3. Брокера реплики не ждут: они к нему не обращаются. Миграции и bootstrap SHALL выполняться один раз за запуск отдельными сервисами, а не репликами. Уборщик SHALL стартовать после готовности PostgreSQL, успешных миграций и успешного bootstrap S3. Relay SHALL стартовать после готовности PostgreSQL и брокера и успешных миграций. Worker SHALL стартовать после готовности PostgreSQL и брокера, успешных миграций и успешного bootstrap S3. Реплики API их не ждут, а фоновую уборку, публикацию заданий и обработку изображений MUST NOT выполнять сами. Уборщик, relay и worker MUST NOT публиковать порты и SHALL перезапускаться после сбоя. Реплики API, worker и остальные сервисы приложения MUST NOT ждать сервисов телеметрии, а сервисы телеметрии MUST NOT ждать готовности друг друга: без них приложение работает, а отправку и запросы они повторяют сами.
Первый запуск на пустых volumes SHALL проходить одной командой с первой попытки: ни один
сервис MUST NOT падать и перезапускаться из-за прав на файлы в своём volume, и make run_docker SHALL завершаться с кодом 0.
Перед этим цель SHALL создавать недостающие .env и config.toml из
шаблонов (make env_setup) и MUST NOT перезаписывать существующие: в
существующий .env она только дописывает переменные шаблона, которых в
нём нет (capability service-configuration, «Подключение к S3»).
make stop SHALL останавливать сервисы, make down — удалять
контейнеры, сохраняя volumes, make logs — показывать журнал всех
реплик API.
Scenario: Штатный запуск
- WHEN в свежем clone выполнен
make run_docker - THEN сервис отвечает через LB на
http://localhost:8080/health/ready, работают две реплики API, уборщик, relay и worker, сервер S3 и брокер в состоянииhealthy, bootstrap S3 завершился с кодом 0, Collector, хранилища телеметрии и Grafana работают, иmake student_testпроходит
Scenario: Миграции один раз
- WHEN выполнен
make run_dockerс двумя репликами - THEN журнал сервиса миграций содержит один прогон, а в журналах реплик API, relay и worker нет запуска миграций
Scenario: Bootstrap S3 один раз
- WHEN выполнен
make run_dockerс двумя репликами - THEN журнал bootstrap S3 содержит один прогон, завершённый до старта реплик, уборщика и worker, а в журналах реплик API нет создания bucket
Scenario: Стенд с нуля одной командой
- WHEN у проекта стенда нет ни одного volume, и выполнен
make run_docker; затем volumes проекта удалены, иmake run_dockerвыполнен ещё раз - THEN оба раза команда завершается с кодом 0 с первой попытки, все долгоживущие сервисы
работают, у брокера и хранилищ телеметрии счётчик перезапусков 0 и нет ошибок прав в
журнале, Grafana отдаёт provisioning, а
make testпечатаетPASS; проверка идёт под отдельным проектом compose, и рабочий стендmtusi-lab6она не затрагивает
Scenario: Приложение без телеметрии
- WHEN Collector, хранилища телеметрии и Grafana остановлены, после чего реплики API и worker перезапущены
- THEN реплики и worker стартуют без ожидания сервисов телеметрии,
/health/readyотвечает 200,make testпечатаетPASS, а вdocker compose configу сервисов приложения нет зависимостей от сервисов телеметрии
Requirement: Порты из .env
Порты стенда и консольного запуска SHALL браться из одного .env:
- внутренний порт API —
APP__PORT: параметр приложения[app] portв формате настроек. Его слушает каждая реплика, на нём работают healthcheck и проверки LB, на нём же LB принимает запросы внутри своего контейнера; - внешний порт стенда —
APP_OUT_PORT: порт LB на127.0.0.1хоста, приложение его не читает; - порт PostgreSQL внутри сети compose —
POSTGRES_PORT, его слушает сам сервер и использует API в docker; - внешний порт PostgreSQL —
POSTGRES_OUT_PORT: порт на127.0.0.1хоста для запуска в консоли; - порт Valkey внутри сети compose —
VALKEY_PORT, внешний —VALKEY_OUT_PORTна127.0.0.1для запуска в консоли; - порт API S3 внутри сети compose —
S3_PORT, его слушает сам сервер S3, используют API в docker и bootstrap; внешний —S3_OUT_PORTна127.0.0.1для запуска в консоли; - порт AMQP брокера внутри сети compose —
RABBITMQ_PORT, его слушает сам брокер, используют relay и worker в docker; внешний —RABBITMQ_OUT_PORTна127.0.0.1для запуска в консоли.
Если переменная порта API не задана, SHALL действовать 8080. Параметры
приложения в .env SHALL записываться в формате настроек
(SECTION__FIELD). Имя без секции допускается только для переменных,
которые приложение не читает. Адреса и порты PostgreSQL, Valkey, S3 и брокера
MUST NOT быть записаны в compose литералами.
Scenario: Другой внешний порт
- WHEN в
.envзаданоAPP_OUT_PORT=8090, и выполненmake run_docker - THEN API доступно через LB на
localhost:8090, а внутри контейнеров реплики слушаютAPP__PORT
Scenario: Другой внутренний порт
- WHEN в
.envзаданоAPP__PORT=9090 - THEN реплики внутри контейнеров слушают 9090 и становятся
healthy, LB проверяет их на 9090, а API доступно наlocalhost:$APP_OUT_PORT
Scenario: Другой порт Postgres
- WHEN в
.envзаданыPOSTGRES_PORT=5544иPOSTGRES_OUT_PORT=5545, а compose не правился - THEN
make run_dockerподнимает стенд,/health/readyотвечает 200, аmake run_devподключается к Postgres на127.0.0.1:5545
Scenario: Другой порт Valkey
- WHEN в
.envзаданы другиеVALKEY_PORTиVALKEY_OUT_PORT, а compose не правился - THEN
make run_dockerиmake run_devподключаются к Valkey на новых портах, и кэш работает
Scenario: Другой порт S3
- WHEN в
.envзаданы другиеS3_PORTиS3_OUT_PORT, а compose не правился - THEN сервер S3 слушает
S3_PORTи становитсяhealthy, bootstrap проходит,make s3_checkпроходит, а приложение в консоли обращается к S3 на127.0.0.1:$S3_OUT_PORT
Scenario: Другой порт брокера
- WHEN в
.envзаданы другиеRABBITMQ_PORTиRABBITMQ_OUT_PORT, а compose не правился - THEN брокер слушает
RABBITMQ_PORTи становитсяhealthy, загрузка через LB становитсяready, а relay и worker в консоли обращаются к брокеру на127.0.0.1:$RABBITMQ_OUT_PORT
Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в REPORT.md SHALL описывать два
способа запуска стенда:
make run_docker— всё в compose;make run_dev— PostgreSQL, Valkey, S3 с bootstrap и брокер в compose, сервис на хосте; relay на хосте —make run_relay, worker на хосте —make run_worker.
Для каждого SHALL быть указаны подготовка (make env_setup), команды,
которые выполняет цель Makefile, применение миграций и bootstrap S3,
ожидание готовности, проверки и остановка.
Scenario: Запуск по отчёту
- WHEN проверяющий в свежем clone выполняет команды из
REPORT.mdдля любого из двух способов - THEN
/health/readyотвечает 200, аmake student_testиmake s3_checkпроходят
Requirement: Публикация только на localhost
Порты LB, PostgreSQL и Valkey, порт API S3, порт AMQP брокера и порт интерфейса Grafana
SHALL публиковаться в compose только на 127.0.0.1 хоста. Адрес публикации SHALL быть
записан литералом, а не переменной; порт Grafana на хосте — GRAFANA_OUT_PORT из .env
(по умолчанию 3000). Другие порты сервера S3 (консоль,
UI, внутренние серверы хранилища), другие порты брокера (метрики, связь узлов), приём OTLP и
метрики Collector, порты Prometheus, Loki и Tempo MUST NOT публиковаться. Реплики API, relay,
worker и одноразовые сервисы MUST NOT публиковать порты на хосте: к репликам ходят только LB
и контейнеры сети compose. Учебный стенд MUST NOT быть доступен с других машин сети.
Scenario: Адрес публикации
- WHEN для запущенных контейнеров LB, API, relay, worker, Postgres, Valkey, S3,
брокера, Collector, Prometheus, Loki, Tempo и Grafana выполняется
docker port - THEN порты LB, Postgres, Valkey, порт API S3, порт AMQP брокера и порт Grafana
опубликованы на
127.0.0.1, а не на0.0.0.0; других портов у S3, брокера и Grafana не опубликовано, а у контейнеров API, relay, worker, Collector, Prometheus, Loki и Tempo опубликованных портов нет
Requirement: Конфигурация на старте
config.toml SHALL подключаться к контейнеру при запуске, только на
чтение, и MUST NOT копироваться в образ. В compose файл SHALL
монтироваться так, чтобы его отсутствие давало явную ошибку запуска, а
не создавало на хосте каталог config.toml/. Секреты, которые нужны и
compose, и приложению, SHALL передаваться через environment (см.
.claude/rules/settings.md).
Scenario: Правка config.toml
- WHEN в
config.tomlизменён[app] log_levelи контейнер перезапущен без пересборки образа - THEN сервис работает с новым уровнем логирования
Scenario: Нет config.toml, запуск через make
- WHEN
make run_dockerзапускается безconfig.toml - THEN
config.tomlсоздаётся изconfig_example.toml, и сервис стартует
Scenario: Нет config.toml, compose напрямую
- WHEN
docker compose upзапускается безconfig.toml - THEN запуск завершается ошибкой о несуществующем источнике
монтирования, и каталог
config.toml/на хосте не появляется
Requirement: Данные переживают рестарт стенда
Данные PostgreSQL, S3 и брокера SHALL храниться в именованных volumes. Скрипт
scripts/restart.sh SHALL перезапускать LB, все реплики API и все
используемые хранилища — PostgreSQL, Valkey, S3 и брокер. Volumes, схема,
bucket, учётные записи S3, очередь, её сообщения и данные SHALL сохраняться: без
удаления volumes, очистки и повторного наполнения. Bootstrap S3, который снова
выполняется при старте реплик, состояние хранилища не меняет. Число
реплик после рестарта SHALL оставаться прежним. Relay, worker и уборщика скрипт не
трогает: они переживают рестарт хранилищ сами, а остановленный worker остаётся
остановленным. Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после
перезапуска, укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка
make test-persistence ACTION_SCRIPT=scripts/restart.sh SHALL проходить через LB.
Scenario: Рестарт hook-ом
- WHEN пользователь вошёл, отправил сообщение, затем выполнен
scripts/restart.sh - THEN контейнеры LB, всех реплик API, Postgres, Valkey, S3 и брокера
перезапущены: те же ID и новое время старта в
docker inspect. После готовности запрос с прежним токеном через LB получает 200 и видит своё сообщение, а bootstrap S3 после рестарта сообщает, что bucket и пользователи уже есть
Scenario: Публичная проверка сохранности
- WHEN на запущенном стенде выполняется
make test-persistence ACTION_SCRIPT=scripts/restart.sh - THEN команда завершается с кодом 0 и печатает
PASS
Scenario: Worker переживает рестарт хранилищ
- WHEN relay и worker работают, выполнен
scripts/restart.sh, и участник загружает файл - THEN вложение становится
ready, а у контейнеров relay и worker прежнее время старта и счётчик перезапусков 0
Requirement: Удаление учебных данных
make stop и make down MUST NOT удалять volumes с данными PostgreSQL,
S3 и брокера. Удаление данных стенда SHALL выполняться отдельной явной командой
make wipe_data, которая запрашивает подтверждение и называет
удаляемые данные.
Scenario: down сохраняет данные
- WHEN выполнены
make down, затемmake run_docker - THEN ранее созданные пользователи, сообщения, объекты S3 и задания в очереди на месте
Scenario: Явное удаление
- WHEN выполнен
make wipe_dataи удаление подтверждено - THEN volumes Postgres, S3 и брокера удалены, и следующий
make run_dockerподнимает пустую базу со схемой из миграций, пустой приватный bucket, созданный bootstrap, и брокер без сообщений
Requirement: Журнал контейнера
Журнал сервиса SHALL выводиться в stdout контейнера в формате
capability service-logging. Между Docker и журналом MUST NOT быть
посторонних строк лаунчера (например, от uv).
Scenario: docker logs
- WHEN выполняется
make logsдля работающего сервиса - THEN каждая строка — JSON-запись сервиса или uvicorn
Requirement: Свой проект compose у лабы
Стенд SHALL запускаться под именем проекта compose mtusi-lab6 с
образом mtusi-messenger:lab6. Контейнеры, сети и volumes стенда
SHALL принадлежать этому проекту. Запуск, остановка и make wipe_data
MUST NOT затрагивать ресурсы проектов прошлых лаб (mtusi-lab5).
Scenario: Данные прошлой лабы не затронуты
- WHEN на машине есть volume
mtusi-lab5_postgres_data, и в этом репозитории выполненыmake run_docker, затемmake wipe_dataс подтверждением - THEN стенд создаёт и затем удаляет только volumes своего проекта
(
mtusi-lab6_postgres_data,mtusi-lab6_s3_data,mtusi-lab6_rabbitmq_data,mtusi-lab6_prometheus_data,mtusi-lab6_loki_data,mtusi-lab6_tempo_data), аmtusi-lab5_postgres_dataостаётся с прежней датой создания
Requirement: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API,
уборщик, relay, worker, сервисы миграций и bootstrap S3, PostgreSQL, Valkey, сервер
S3, брокер, Collector, Prometheus, Loki, Tempo и Grafana. Сумма лимитов против ресурсов ВМ
Docker и расчёт соединений PostgreSQL для заявленного числа
реплик, уборщика, relay и worker SHALL быть описаны в REPORT.md. Сервисы на Go с лимитом
памяти SHALL получать предел памяти рантайма меньше лимита контейнера: лимит cgroup они сами
не видят. Секреты SHALL
передаваться только тем сервисам, которым они нужны:
- пароль PostgreSQL — PostgreSQL, репликам API, уборщику, relay, worker и сервису миграций;
- пароль Valkey — Valkey и репликам API;
- пароль брокера — брокеру, relay и worker;
- административные ключ и секрет S3 — только серверу S3;
- ключ подписи служебных вызовов S3 — серверу S3 и bootstrap;
- ключи пользователя API в S3 — bootstrap и репликам API;
- ключи пользователя уборщика в S3 — bootstrap и уборщику;
- ключи пользователя worker в S3 — bootstrap и worker;
- пароль администратора Grafana — только Grafana;
- LB MUST NOT получать ни одного секрета, а сервис миграций, PostgreSQL, Valkey и брокер MUST NOT получать секретов S3. Реплики API MUST NOT получать пароль брокера. Уборщик MUST NOT получать пароли Valkey и брокера, ключи API и worker, административные ключи S3 и ключ подписи. Relay MUST NOT получать пароль Valkey и секреты S3. Worker MUST NOT получать пароль Valkey, ключи API и уборщика, административные ключи S3 и ключ подписи. Collector, Prometheus, Loki и Tempo MUST NOT получать ни одного секрета; адрес Collector секретом не является, и для телеметрии реплики API и worker новых секретов не получают.
Scenario: Лимиты у всех контейнеров
- WHEN для каждого контейнера запущенного стенда выполняется
docker inspect(HostConfig.NanoCpus,HostConfig.Memory) - THEN у LB, каждой реплики API, уборщика, relay, worker, сервисов миграций и bootstrap S3, PostgreSQL, Valkey, сервера S3, брокера, Collector, Prometheus, Loki, Tempo и Grafana оба значения больше нуля
Scenario: Секреты по сервисам
- WHEN проверяющий смотрит окружение сервисов в
docker compose config - THEN у LB нет ни одного секрета; у сервиса миграций нет паролей Valkey и брокера и секретов S3; пароль Valkey есть только у Valkey и реплик API; пароль брокера — только у брокера, relay и worker; административные ключи S3 — только у сервера S3, ключ подписи — у сервера S3 и bootstrap, ключи API в S3 — у bootstrap и реплик API, ключи уборщика в S3 — у bootstrap и уборщика, ключи worker в S3 — у bootstrap и worker; пароль администратора Grafana — только у Grafana, а у Collector, Prometheus, Loki и Tempo секретов нет