Files
mtusi2026lab6/openspec/specs/container-run/spec.md
T
2026-11-11 11:31:22 +03:00

369 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 секретов нет