Files
mtusi2026lab3/openspec/specs/container-run/spec.md
T
ricoromaandClaude Opus 5.5 ab71c3b51e feat: put API replicas behind HAProxy
HAProxy 3.4 is the only published entry point; api runs as
API_REPLICAS replicas without ports, found through Docker DNS and
checked on /health/ready. Retries only on connection failure, LB errors
in the contract error format, resource limits and per-service secrets.
Adds scripts/stop-one.sh, LB-aware restart.sh, make replicas /
instances / lb_stats and replica tests driven by EXPECT_REPLICAS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 18:05:05 +03:00

241 lines
14 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, одноразовыми миграциями и API (`make run_docker`), публикация
портов только на localhost, конфигурация на старте, сохранность данных
при рестарте стенда и явное удаление учебных данных.
## Requirements
### Requirement: Запуск через compose
`make run_docker` SHALL собирать образ и поднимать стенд через
`docker compose`: PostgreSQL, Valkey, одноразовый сервис миграций,
`API_REPLICAS` реплик API (capability `load-balancing`) и балансировщик
(LB). Реплики API SHALL стартовать после готовности PostgreSQL и Valkey
и успешных миграций. Миграции SHALL выполняться один раз за запуск
отдельным сервисом, а не репликами. Перед этим цель SHALL создавать
недостающие `.env` и `config.toml` из шаблонов (`make env_setup`) и
MUST NOT перезаписывать существующие. `make stop` SHALL останавливать
сервисы, `make down` — удалять контейнеры, сохраняя volume, `make logs`
— показывать журнал всех реплик API.
#### Scenario: Штатный запуск
- **WHEN** в свежем clone выполнен `make run_docker`
- **THEN** сервис отвечает через LB на
`http://localhost:8080/health/ready`, работают две реплики API, и
`make student_test` проходит
#### Scenario: Миграции один раз
- **WHEN** выполнен `make run_docker` с двумя репликами
- **THEN** журнал сервиса миграций содержит один прогон, а в журналах
реплик API нет запуска миграций
### 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 не задана, SHALL действовать 8080. Параметры
приложения в `.env` SHALL записываться в формате настроек
(`SECTION__FIELD`). Имя без секции допускается только для переменных,
которые приложение не читает. Адреса и порты PostgreSQL и Valkey 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 на
новых портах, и кэш работает
### Requirement: Оба способа запуска описаны в REPORT.md
Раздел «Запуск из чистого clone» в `REPORT.md` SHALL описывать два
способа запуска стенда: `make run_docker` (всё в compose) и
`make run_dev` (Postgres в compose, сервис на хосте). Для каждого SHALL
быть указаны подготовка (`make env_setup`), команды, которые выполняет
цель Makefile, применение миграций, ожидание готовности, проверки и
остановка.
#### Scenario: Запуск по отчёту
- **WHEN** проверяющий в свежем clone выполняет команды из `REPORT.md`
для любого из двух способов
- **THEN** `/health/ready` отвечает 200, а `make student_test` проходит
### Requirement: Публикация только на localhost
Порты LB, PostgreSQL и Valkey SHALL публиковаться в compose только на
`127.0.0.1` хоста. Адрес публикации SHALL быть записан литералом, а не
переменной. Реплики API MUST NOT публиковать порты на хосте: к ним
ходят только LB и контейнеры сети compose. Учебный стенд MUST NOT быть
доступен с других машин сети.
#### Scenario: Адрес публикации
- **WHEN** для запущенных контейнеров LB, API, Postgres и Valkey
выполняется `docker port`
- **THEN** порты LB, Postgres и Valkey опубликованы на `127.0.0.1`, а
не на `0.0.0.0`, а у контейнеров API опубликованных портов нет
### 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 SHALL храниться в именованном volume. Скрипт
`scripts/restart.sh` SHALL перезапускать LB, все реплики API и все
используемые хранилища — PostgreSQL и Valkey. Volume, схема и данные
SHALL сохраняться: без удаления volume, очистки и повторного
наполнения. Число реплик после рестарта SHALL оставаться прежним.
Скрипт 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
перезапущены: те же ID и новое время старта в `docker inspect`. После
готовности запрос с прежним токеном через LB получает 200 и видит
своё сообщение
#### Scenario: Публичная проверка сохранности
- **WHEN** на запущенном стенде выполняется `make test-persistence
ACTION_SCRIPT=scripts/restart.sh`
- **THEN** команда завершается с кодом 0 и печатает `PASS`
### Requirement: Удаление учебных данных
`make stop` и `make down` MUST NOT удалять volume с данными. Удаление
данных стенда SHALL выполняться отдельной явной командой
`make wipe_data`, которая запрашивает подтверждение.
#### Scenario: down сохраняет данные
- **WHEN** выполнены `make down`, затем `make run_docker`
- **THEN** ранее созданные пользователи и сообщения на месте
#### Scenario: Явное удаление
- **WHEN** выполнен `make wipe_data` и удаление подтверждено
- **THEN** volume Postgres удалён, и следующий `make run_docker`
поднимает пустую базу со схемой из миграций
### Requirement: Журнал контейнера
Журнал сервиса SHALL выводиться в stdout контейнера в формате
capability `service-logging`. Между Docker и журналом MUST NOT быть
посторонних строк лаунчера (например, от `uv`).
#### Scenario: docker logs
- **WHEN** выполняется `make logs` для работающего сервиса
- **THEN** каждая строка — JSON-запись сервиса или uvicorn
### Requirement: Свой проект compose у лабы
Стенд SHALL запускаться под именем проекта compose `mtusi-lab3` с
образом `mtusi-messenger:lab3`. Контейнеры, сети и volumes стенда
SHALL принадлежать этому проекту. Запуск, остановка и `make wipe_data`
MUST NOT затрагивать ресурсы проектов прошлых лаб (`mtusi-lab2`).
#### Scenario: Данные прошлой лабы не затронуты
- **WHEN** на машине есть volume `mtusi-lab2_postgres_data`, и в этом
репозитории выполнены `make run_docker`, затем `make wipe_data` с
подтверждением
- **THEN** стенд создаёт и затем удаляет только
`mtusi-lab3_postgres_data`, а `mtusi-lab2_postgres_data` остаётся с
прежней датой создания
### Requirement: Лимиты ресурсов и секреты по сервисам
Каждый сервис стенда SHALL иметь лимиты CPU и памяти: LB, реплики API,
сервис миграций, PostgreSQL и Valkey. Сумма лимитов и расчёт
соединений PostgreSQL для заявленного числа реплик SHALL быть описаны
в `REPORT.md`. Секреты SHALL передаваться только тем сервисам, которым
они нужны:
- пароль PostgreSQL — PostgreSQL, репликам API и сервису миграций;
- пароль Valkey — Valkey и репликам API;
- LB MUST NOT получать ни одного секрета.
#### Scenario: Лимиты у всех контейнеров
- **WHEN** для каждого контейнера запущенного стенда выполняется
`docker inspect` (`HostConfig.NanoCpus`, `HostConfig.Memory`)
- **THEN** у LB, каждой реплики API, сервиса миграций, PostgreSQL и
Valkey оба значения больше нуля
#### Scenario: Секреты по сервисам
- **WHEN** проверяющий смотрит окружение сервисов в
`docker compose config`
- **THEN** у LB нет ни одного пароля, у сервиса миграций нет пароля
Valkey, а пароль Valkey есть только у Valkey и реплик API