# 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 (capability `load-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 секретов нет