Valkey 9.1 in compose caches the immutable chat card (title, members,
created_at) used by GET /chats/{id} and by the membership check of the
message endpoints. Cache-aside with a write after commit, keys per
database, TTL plus allkeys-lru, persistence off. redis-py runs without
retries; on failure the cache is skipped for a few seconds and requests
go to PostgreSQL. Readiness does not depend on Valkey.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
container-run Specification
Purpose
Как стенд сервиса запускается и настраивается: compose с PostgreSQL,
Valkey, одноразовыми миграциями и API (make run_docker), публикация
портов только на localhost, конфигурация на старте, сохранность данных
при рестарте стенда и явное удаление учебных данных.
Requirements
Requirement: Запуск через compose
make run_docker SHALL собирать образ и поднимать стенд через
docker compose: PostgreSQL, Valkey, одноразовый сервис миграций и API.
API SHALL стартовать после готовности PostgreSQL и Valkey и успешных
миграций. Перед этим цель 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 сервис отвечает на
http://localhost:8080/health/ready, иmake student_testпроходит
Requirement: Порты из .env
Порты стенда и консольного запуска SHALL браться из одного .env:
- внутренний порт API —
APP__PORT: параметр приложения[app] portв формате настроек, на нём же работает healthcheck; - внешний порт API —
APP_OUT_PORT: порт на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 доступно на
localhost:8090, а внутри контейнера сервис слушаетAPP__PORT
Scenario: Другой внутренний порт
- WHEN в
.envзаданоAPP__PORT=9090 - THEN сервис внутри контейнера слушает 9090, контейнер становится
healthy, а 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
Порты API, PostgreSQL и Valkey SHALL публиковаться в compose только на
127.0.0.1 хоста. Адрес публикации SHALL быть записан литералом, а не
переменной. Учебный стенд MUST NOT быть доступен с других машин сети.
Scenario: Адрес публикации
- WHEN для запущенных контейнеров API, Postgres и Valkey выполняется
docker port - THEN порты опубликованы на
127.0.0.1, а не на0.0.0.0
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 перезапускать API и все используемые
хранилища — PostgreSQL и Valkey, — сохраняя volume, схему и данные: без
удаления volume, очистки и повторного наполнения. Скрипт SHALL быть
исполняемым, завершаться с кодом 0 только после перезапуска,
укладываться в 90 с и MUST NOT печатать секреты. Публичная проверка
make test-persistence ACTION_SCRIPT=scripts/restart.sh SHALL
проходить.
Scenario: Рестарт hook-ом
- WHEN пользователь вошёл, отправил сообщение, затем выполнен
scripts/restart.sh - THEN контейнеры API, Postgres и Valkey перезапущены (новое время
старта в
docker inspect), а после готовности запрос с прежним токеном получает 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