Files
mtusi2026lab4/openspec/changes/archive/2026-09-29-container-runtime/proposal.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- carry the lab 3 solution over from mtusi2026lab3-safronov
  (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests,
  bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts,
  Dockerfile, compose, pyproject and uv lock
- merge Makefile, .gitignore and .dockerignore (the lab 3 versions only
  add lines to the skeleton, which is the same in lab 4) and
  .env.example (lab 4 skeleton names listed in the header)
- rename the compose project to mtusi-lab4 and the image to :lab4 so
  the stand does not reuse the lab 3 containers and volumes
- update AGENTS.md for lab 4: current lab, origin commit, contract and
  test files of the new skeleton

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:32:33 +03:00

5.8 KiB
Raw Blame History

Proposal

Why

API лабы 1 работает только на хосте через make run_dev. Рубрика требует собирать приложение Dockerfile из исходников и публиковать API через docker run на localhost:8080. Это уровень «3». Уровень «4» требует непривилегированного пользователя, закреплённых версий, .dockerignore, остановки по SIGTERM не дольше 10 с и healthcheck (README.md). Без контейнера нельзя показать ни сценарий защиты, ни трек 1: там замеры идут при фиксированных лимитах CPU и памяти контейнера.

What Changes

  • Dockerfile. Мультистейдж в стиле bp_proxies:
    • builder ставит зависимости из uv.lock, runtime получает только .venv и src/;
    • базовый образ и uv закреплены версией и digest;
    • процесс работает под непривилегированным пользователем, сервер — PID 1 (python -m src);
    • HEALTHCHECK ходит на /health/ready;
    • config.toml, .env и секреты в образ не попадают.
  • .dockerignore. Дополняется, чтобы в контекст сборки не уходили config.toml, .claude, openspec, тесты, контракты и документация.
  • docker-compose.yml. Сервис api в стиле bp_proxies:
    • порты из .env (APP_OUT_PORT снаружи, APP__PORT внутри) и публикация только на 127.0.0.1;
    • config.toml монтируется read-only;
    • stop_grace_period и healthcheck.
  • .env.example. Переписывается: параметры приложения — в формате настроек (APP__PORT), без секции — только то, что приложение не читает (APP_OUT_PORT). Как переменные из .env.example skeleton соотносятся с реальными, описано в REPORT.md.
  • Остановка по SIGTERM за заявленный срок. Новые соединения отклоняются, текущие запросы дорабатывают, процесс выходит не дольше чем за 10 с. Это проверяется замером и логами.
  • Цели Makefile: два способа запуска, оба описаны в REPORT.md:
    • run_no_compose — голый docker build + docker run из README с портами из .env, контейнер на переднем плане;
    • run_docker — compose, к нему stop, down, logs.
  • Доказательства в evidence/ и разделы REPORT.md:
    • запуск из чистого clone обоими способами;
    • соответствие переменных .env.example реальной конфигурации;
    • строки таблицы критериев для контейнера — сборка и запуск, потеря состояния после рестарта, non-root, пины, .dockerignore, SIGTERM, healthcheck, логи.
  • Не входит: собственные тесты и тест гонок (change student-tests), нагрузочные эксперименты (трек 1), остальные строки REPORT.md.

Capabilities

New Capabilities

  • container-image: как собирается образ и что в нём есть — сборка из чистого clone по lock, закреплённые версии, непривилегированный пользователь, отсутствие конфигов и секретов, healthcheck.
  • container-run: как контейнер запускается и настраивается — docker run из README и compose, порты, конфигурация на старте, потеря состояния при рестарте контейнера.
  • graceful-shutdown: поведение процесса по SIGTERM — перестать принимать запросы, доработать текущие и завершиться за заявленный срок.

Modified Capabilities

Нет. Режим docker (адрес 0.0.0.0, без автоперезапуска) уже описан в service-configuration, а JSON-логи в stdout — в service-logging. Контейнер использует их без изменения требований.

Impact

  • Новые файлы: Dockerfile, docker-compose.yml, файлы в evidence/.
  • Изменяемые файлы:
    • .dockerignore — дополнение, файл skeleton не заменяется;
    • .env.example;
    • config_example.toml — без port: порт задаётся в .env;
    • Makefile — новая секция, цели skeleton не трогаются;
    • REPORT.md — разделы запуска, конфигурации и строки критериев контейнера;
    • AGENTS.md — таблица команд;
    • .claude/rules/docker.md, если при реализации уточнятся детали.
  • Код приложения не меняется: режим docker, timeout_graceful_shutdown и health уже есть. Правка возможна, только если замер SIGTERM покажет проблему.
  • Окружение: Docker Engine с BuildKit. На машине автора — Docker Desktop 29.8 для macOS.