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>
241 lines
14 KiB
Markdown
241 lines
14 KiB
Markdown
# 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
|