- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec change instance-id-idempotency) - rename the compose project to mtusi-lab3 and the image to :lab3 - add X-Instance-Id to every response and instance_id to every log record ([app] instance_id, hostname by default) - require Idempotency-Key on POST messages: keys table in Postgres, key and message in one transaction, replay returns the same 201, another body gets 409, TTL from [idempotency] ttl_seconds - send the key from student-tests, k6 scenarios and the skill driver; add idempotency, X-Instance-Id, key race and fault tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
23 KiB
Design
Context
Мотивация — proposal.md, раздел Why. Требования — specs/.
Приложение уже готово к контейнеру (change messenger-core-api):
- режим
APP__RUN_MODE=dockerслушает0.0.0.0без reload; uvicorn.runполучаетtimeout_graceful_shutdownиз[app] graceful_shutdown_seconds(8 с, валидатор не пускает больше 9 с);/health/readyисключён из итоговой записи о запросе;- логи — JSON в stdout, включая строки uvicorn.
Форму Dockerfile и compose задают .claude/rules/docker.md и
run-modes.md: мультистейдж с uv и compose в стиле bp_proxies.
config.toml монтируется на старте, это согласовано с преподавателем
(AGENTS.md). Цели Makefile оформляются так же, как в bp_proxies, без
Apple Container.
Факты, проверенные при планировании:
- Образы. Последний патч Python 3.12 —
python:3.12.14-slim-trixie(Debian 13), uv —ghcr.io/astral-sh/uv:0.12.17, та же версия, что локально. Оба digest — индексы для нескольких архитектур (amd64 и arm64):python:3.12.14-slim-trixie@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51fghcr.io/astral-sh/uv:0.12.17@sha256:10787c682e4184e4f290de1171fd4703dc63de99221f10fe1c99002ce7fa9acc
- uvicorn 0.54 на SIGTERM. Сначала закрывает слушающий сокет, затем
закрывает простаивающие соединения, ждёт текущие запросы до
timeout_graceful_shutdownи отменяет оставшиеся. После этого выполняет shutdown в lifespan и повторно шлёт себе пойманный сигнал черезsignal.raise_signal.
Goals / Non-Goals
Goals:
docker buildиdocker runиз README работают из чистого clone без подготовительных шагов,make testпроходит против контейнера.- Уровень «4» по контейнеру проверяется командами:
- non-root;
- пины версий и digest;
.dockerignore;- остановка по SIGTERM быстрее 10 с;
- healthcheck;
- журнал без содержимого сообщений.
- Доказательства лежат в
evidence/container/и в строкахREPORT.md, а не только в выводе терминала.
Non-Goals:
- Лимиты CPU и памяти контейнера — их задаст методика трека 1 в отдельном change.
- Сборка образа под чужую архитектуру и публикация в registry: собираем локально под платформу хоста, а пины через индекс работают на обеих архитектурах.
- CI-сборка образа (
CONTRIBUTING.mdпредлагает отдельный job в CI) — по желанию, позже.
Decisions
1. Dockerfile: два stage на одном базовом образе
FROM python:3.12.14-slim-trixie@sha256:… AS builder
COPY --from=ghcr.io/astral-sh/uv:0.12.17@sha256:… /uv /bin/uv
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never \
UV_PROJECT_ENVIRONMENT=/app/.venv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
uv sync --locked --no-dev --no-install-project
FROM python:3.12.14-slim-trixie@sha256:… AS runtime
RUN groupadd --system --gid 10001 app \
&& useradd --system --uid 10001 --gid app --no-create-home \
--home-dir /nonexistent --shell /usr/sbin/nologin app
ENV PATH=/app/.venv/bin:$PATH PYTHONUNBUFFERED=1 \
PYTHONDONTWRITEBYTECODE=1 APP__RUN_MODE=docker
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src ./src
USER app
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=3s --start-period=10s \
--start-interval=1s --retries=3 \
CMD ["python", "-c", "import os, urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/health/ready' % os.environ.get('APP__PORT', '8080'), timeout=2)"]
CMD ["python", "-m", "src"]
- Один базовый образ в обоих stage. Интерпретатор в
.venv— это ссылка на/usr/local/bin/python3.12базового образа. Если builder взять на другом образе, в runtime.venvперестанет работать. --no-install-project. Проект не ставится в.venvкак пакет: hatchling собрал бы его изsrc/, которого в builder ещё нет.python -m srcзапускается из/app, иsrcнаходится через текущий каталог.- Код без права записи. Код и
.venvкопируются от root и принадлежат root. Пользовательapp(UID 10001) может их только читать — это требование «код только на чтение».PYTHONDONTWRITEBYTECODEубирает попытки записать.pycрядом сsrc/. Зависимости скомпилированы в builder (UV_COMPILE_BYTECODE). - Кеш сборки. Слой зависимостей пересобирается только при изменении
pyproject.tomlилиuv.lock. Cache mount ускоряет повторныйuv sync, но в образ не попадает. - Порт в healthcheck. Берётся из
APP__PORT, как у сервиса, значение по умолчанию — 8080. Так healthcheck работает и в README-запуске, и в compose, где порт может быть другим. --start-interval=1s. Во времяstart_periodпроверка идёт раз в секунду. Без этого первая проверка — только черезinterval(10 с), и контейнер не станетhealthyдо концаstart_period, как требует спека. Флаг поддерживается с Docker Engine 25.- Отличия от bp_proxies:
- uv не ставится
pip installбез версии и не нужен в runtime; config.tomlне копируется в образ;- сервер запускается как PID 1 без
uv run.
- uv не ставится
Альтернативы:
python:3.12-slimбез пина — запрещено рубрикой.- Bookworm вместо trixie — trixie актуальный stable Debian, а
3.12.14-slim-bookwormтоже есть и нужен, только если найдётся несовместимость. - Distroless: сложнее отлаживать на защите (
docker execбез shell), и пришлось бы переносить интерпретатор. Выигрыш в размере для учебного стенда не нужен.
2. Пины: тег и digest индекса
В FROM и COPY --from пишется тег@sha256:<digest индекса>. Тег
говорит, какая это версия, digest гарантирует повторяемость, даже если
тег перепубликуют с обновлениями безопасности. Digest индекса, а не
манифеста одной платформы, одинаково работает на arm64 (машина автора) и
amd64 (стенд преподавателя). Обновление версии — осознанная правка:
новый тег и digest из docker buildx imagetools inspect <тег>.
3. .dockerignore
Файл из skeleton дополняется, а не заменяется (docker.md):
config.toml, .claude, openspec, tests, student-tests,
contracts, scripts, examples, *.md, Makefile, .ruff_cache,
.idea, .python-version, а также **/__pycache__, **/*.py[cod],
**/.DS_Store: паттерн skeleton __pycache__ без **/ действует
только в корне, и .pyc хоста из src/ попадали в образ (найдено при
проверке состава). Dockerfile копирует только
pyproject.toml, uv.lock и src, так что .dockerignore — вторая
линия защиты и способ уменьшить контекст сборки.
4. compose
services:
api:
build: .
image: mtusi-messenger:lab1
restart: unless-stopped
ports:
- "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"
environment:
- APP__RUN_MODE=docker
- APP__PORT=${APP__PORT:-8080}
volumes:
- type: bind
source: ./config.toml
target: /app/config.toml
read_only: true
bind:
create_host_path: false
stop_grace_period: 10s
- Healthcheck не дублируется: compose берёт его из образа.
- Тег образа тот же, что в README (
mtusi-messenger:lab1), поэтомуdocker runиз README и compose используют один образ. - Длинная запись bind-mount и её поведение при отсутствии файла
проверены при подготовке правил (
docker.md).
5. .env.example: параметры приложения — в формате настроек
Переменная, которая касается самого приложения, пишется в .env в
формате настроек (SECTION__FIELD), даже если её читает и compose.
Имя без секции — только у того, что приложение не читает:
# порт сервиса ([app] port): на нём слушает приложение, его же
# публикуют compose и make run_no_compose, на нём же healthcheck
APP__PORT=8080
# порт на 127.0.0.1 хоста, куда публикуется сервис; приложение его
# не читает
APP_OUT_PORT=8080
-
Кто читает
APP__PORT. Все три способа запуска:run_dev— pydantic-settings из.envна хосте;run_no_compose— из окружения контейнера (--env-file .env);- compose — через
environment.
Порт всегда задаётся в
.env, поэтомуportубирается изconfig_example.toml: по приоритету (окружение >.env>config.toml) значение в toml всё равно ни на что бы не влияло. ПолеApp.portс дефолтом 8080 остаётся. Пример в шапкеconfig_example.tomlменяется сAPP__PORTнаAPP__LOG_LEVEL. В локальномconfig.tomlстрокаportбезвредна, но её лучше убрать руками. -
Мосты не нужны. Мост
SECTION__FIELD=${VAR}остаётся для значений, чьё имя навязано контейнером зависимости (с лабы 2 —DATABASE__PASSWORD=${POSTGRES_PASSWORD}). Порт приложения принадлежит приложению, и compose читает${APP__PORT}напрямую. -
Комментарии в
.env— только отдельными строками. Makefile читает.envчерезinclude(решение 6), а make, в отличие от compose, оставляет пробел перед# комментарийв конце строки частью значения.
Переменные skeleton соотносятся так, и это записывается в REPORT.md:
APP_HOSTне нужен: адрес следует из режима (0.0.0.0в docker);APP_PORT— этоAPP__PORT([app] port), внешний порт отдельно —APP_OUT_PORT;APP_ENV— этоAPP__RUN_MODE, его задают Dockerfile и compose.
Локальный .env, созданный из старого шаблона, содержит APP_PORT,
который ни на что не влияет. Его нужно обновить руками: make env_setup существующий файл не перезаписывает.
6. Цели Makefile: два способа запуска
Новая секция Docker targets в стиле run-modes.md. Переменные — в
начале секции, а не в начале файла: верх Makefile принадлежит
skeleton, и свои секции при переходе в следующую лабу переносятся
целиком.
# порты — из того же .env, что читает compose; без .env — 8080
-include .env
APP__PORT ?= 8080
APP_OUT_PORT ?= 8080
DC=docker compose
DOCKER_IMAGE=mtusi-messenger:lab1
DOCKER_CONTAINER=mtusi-messenger-lab1
Способов запуска два, и оба входят в REPORT.md (решение 9):
run_no_compose— команды README без compose, порты из.env:run_no_compose: env_setup DOCKER_BUILDKIT=1 docker build -t $(DOCKER_IMAGE) . docker run --rm --name $(DOCKER_CONTAINER) \ -p 127.0.0.1:$(APP_OUT_PORT):$(APP__PORT) \ --env-file .env $(DOCKER_IMAGE)- Порты работают так же, как в compose:
APP_OUT_PORTснаружи,APP__PORTвнутри. Приложение само читаетAPP__PORTиз окружения контейнера, и healthcheck стучится туда же. С.envиз шаблона команда совпадает с README буква в букву (-p 127.0.0.1:8080:8080). - Разовая подмена внешнего порта — аргументом make, для обеих целей:
make run_no_compose APP_OUT_PORT=8090,make run_docker APP_OUT_PORT=8090. Внутренний порт меняется только в.env:make run_no_compose APP__PORT=9090поменял бы маппинг-p, а приложение взяло быAPP__PORTиз--env-file .env. Префикс окружения (APP_OUT_PORT=8090 make ...) не работает: присваивание из.envперекрывает переменную окружения, и make экспортирует в recipe уже значение из.env, в том числе дляdocker compose(проверено на GNU Make 3.81). Аргумент make перекрывает.envи экспортируется. Голыйdocker compose upбез make работает по правилам compose: окружение важнее.env. - Контейнер работает на переднем плане, как в README («в другом терминале: make test»): журнал виден сразу. make печатает команды, поэтому в выводе видно, что именно выполняется.
- Ctrl+C: docker CLI без
-tпередаёт SIGINT процессу 1 (--sig-proxyпо умолчанию), uvicorn останавливается штатно, как на SIGTERM.--rmудаляет контейнер. Из другого терминала —docker stop mtusi-messenger-lab1. Отдельная цель остановки не нужна. config.tomlне монтируется: это сценарий README «без compose и безconfig.toml». Параметры приложения, кроме заданных в.env, берутся по умолчанию. Свойconfig.toml— через compose.- Нужен
.env(--env-file): без негоdocker runпадает. Поэтому цель зависит отenv_setup, как иrun_docker: недостающие файлы создаются из шаблонов, существующие не трогаются.-include .envчитается при разборе Makefile, раньшеenv_setup. Поэтому при первом запуске без.envв-pидут значения по умолчанию, 8080 — те же, что в шаблоне.
- Порты работают так же, как в compose:
run_docker: env_setup— compose: сначалаenv_setupсоздаёт недостающие.envиconfig.tomlиз шаблонов (существующие не трогает), затемDOCKER_BUILDKIT=1 $(DC) buildи$(DC) up -d. Такmake run_dockerработает в свежем clone без подготовки, а голыйdocker compose upбезconfig.tomlпо-прежнему падает с явной ошибкой вместо каталогаconfig.toml/. Для него жеstop,down,logs($(DC) logs -f --no-log-prefix api: без префиксаapi-1 |каждая строка — JSON).
Оба способа собирают один образ mtusi-messenger:lab1 и публикуют
127.0.0.1:$(APP_OUT_PORT) из одного .env. Одновременно работает
только один из них, иначе второй не получит порт.
Цели skeleton не меняются.
7. Как проверяем SIGTERM
- Поднять контейнер и запустить
tests/load.pyна 20 с в фоне. - Через несколько секунд выполнить
time docker stop <контейнер>. - Зафиксировать:
- время
docker stop(должно быть меньше 10 с); docker inspect -f '{{.State.ExitCode}}'(не 137);- строки журнала
Shutting down→Stopped API→Finished server processс метками времени; - отчёт
load.py: запросы после сигнала — ошибки соединения, а не ответы.
- время
Ожидаемый код выхода — 0. uvicorn после остановки повторно шлёт себе SIGTERM, но ядро не доставляет процессу с PID 1 сигнал без установленного обработчика, и Python завершается обычным образом. Если окажется 143, это тоже корректная остановка, а не SIGKILL. Фиксируем фактическое значение.
8. Сборка «из чистого clone» без коммита
git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t mtusi-messenger:lab1 -
В контекст попадают ровно те файлы, которые попали бы в clone после
коммита: отслеживаемые и новые, но не игнорируемые. config.toml,
.env и .venv исключаются .gitignore. Так проверка не требует ни
коммита, ни временного каталога. Финальная проверка настоящим
git clone делается перед PR, когда изменения закоммичены.
9. Доказательства и REPORT.md
-
evidence/container/— текстовые выводы команд без секретов и без текстов сообщений: сборка,docker runиmake test, жизненный цикл с рестартом,id -uи запись вsrc/,docker inspect(healthcheck, пользователь), SIGTERM. -
REPORT.md:- раздел «Запуск из чистого clone»: версии, prerequisites и оба
способа из решения 6. Для каждого: подготовка (обе цели сами
вызывают
make env_setup), цель Makefile и команды, которые она выполняет, ожидание готовности (/health/readyилиhealthyвdocker ps),make test, остановка. Первым идётmake run_no_compose: он повторяет README. Сразу за ним —make run_dockerс портом иconfig.toml; - часть раздела «Архитектура и решения»: процессы и хранилище,
соответствие
.env.example, согласования с преподавателем; - строки таблицы критериев для этого change со ссылками на файлы
evidence/.
Остальные TODO остаются для
student-testsи трека. - раздел «Запуск из чистого clone»: версии, prerequisites и оба
способа из решения 6. Для каждого: подготовка (обе цели сами
вызывают
Risks / Trade-offs
- [Базовый образ под тегом со временем получает исправления, а мы на
старом digest] → Это осознанная цена воспроизводимости. Обновление —
правка тега и digest с пересборкой, порядок описан в
docker.md. - [На Linux хосте
config.tomlс правами600не прочитать пользователю UID 10001] → Вdocker.mdуже сказано про режим644. ВREPORT.mdдобавить строку о правах. - [Docker Desktop на macOS: время остановки и сеть идут через VM] → Замер SIGTERM показывает поведение процесса, а не сети. Числа фиксируются вместе с окружением (версия Docker Desktop, архитектура).
- [Healthcheck раз в 10 с запускает Python-процесс в контейнере] →
Около 30 мс CPU на проверку. На замерах трека 1 это нужно учесть или
отключить через
--no-healthcheck, и записать это в методику. - [
restart: unless-stoppedподнимет контейнер после рестарта Docker] → Для учебного стенда это удобно. Остановка черезmake stopсохраняется.
Migration Plan
Не применимо: новые файлы инфраструктуры, данных нет. Откат — удалить
Dockerfile и docker-compose.yml, вернуть .dockerignore,
.env.example, config_example.toml, Makefile и REPORT.md из
git.