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

25 KiB
Raw Blame History

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 секретов нет