Files
mtusi2026lab2/openspec/specs/container-run/spec.md
T
ricoromaandClaude Opus 5.5 2d0a7c83e9 feat: finish postgres-storage change
- keep engine and session factory in src/infra/db/session.py
- sync delta specs into openspec/specs, add db-migrations spec
- update rules, AGENTS.md and run skill for lab 2 storage
- fill REPORT.md for the storage part

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 16:20:49 +03:00

9.0 KiB
Raw Blame History

container-run Specification

Purpose

Как стенд сервиса запускается и настраивается: compose с PostgreSQL, одноразовыми миграциями и API (make run_docker), публикация портов только на localhost, конфигурация на старте, сохранность данных при рестарте стенда и явное удаление учебных данных.

Requirements

Requirement: Запуск через compose

make run_docker SHALL собирать образ и поднимать стенд через docker compose: PostgreSQL, одноразовый сервис миграций и API. API SHALL стартовать после готовности PostgreSQL и успешных миграций. Перед этим цель 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 хоста для запуска в консоли.

Если переменная порта API не задана, SHALL действовать 8080. Параметры приложения в .env SHALL записываться в формате настроек (SECTION__FIELD). Имя без секции допускается только для переменных, которые приложение не читает. Адрес и порт PostgreSQL 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

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 SHALL публиковаться в compose только на 127.0.0.1 хоста. Адрес публикации SHALL быть записан литералом, а не переменной. Учебный стенд MUST NOT быть доступен с других машин сети.

Scenario: Адрес публикации

  • WHEN для запущенных контейнеров API и Postgres выполняется 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 и все используемые хранилища, сохраняя volume, схему и данные: без удаления volume, очистки и повторного наполнения. Скрипт SHALL быть исполняемым, завершаться с кодом 0 только после перезапуска, укладываться в 90 с и MUST NOT печатать секреты.

Scenario: Рестарт hook-ом

  • WHEN пользователь создан, отправил сообщение, затем выполнен scripts/restart.sh
  • THEN контейнеры API и Postgres перезапущены (новое время старта в docker inspect), а после готовности запрос с прежним X-User-Id получает 200 и видит своё сообщение

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