Files
mtusi2026lab3/.claude/rules/docker.md
T
ricoromaandClaude Opus 5.5 ab71c3b51e feat: put API replicas behind HAProxy
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>
2026-10-10 18:05:05 +03:00

16 KiB
Raw Blame History

paths
paths
Dockerfile
docker-compose.yml
.dockerignore
scripts/restart.sh
infra/**

Dockerfile и compose

Форма — как в bp_proxies: мультистейдж с uv, compose с портами из .env, литеральным режимом в environment и python-healthcheck. Требования рубрики (README.md, уровни 3 и 4) и Dockerfile.example важнее образца; отличия от него перечислены ниже. Режимы запуска — run-modes.md.

Dockerfile

  • Мультистейдж. В builder — uv sync --locked --no-dev --no-install-project по pyproject.toml и uv.lock в /app/.venv: слой зависимостей кешируется отдельно от кода. В runtime — копия .venv и src/, PATH на /app/.venv/bin. Компиляторы и uv в runtime не нужны (в bp_proxies uv ставился в оба stage).
    • Оба stage — на одном базовом образе: .venv/bin/python — ссылка на интерпретатор базового образа, на другом образе она сломается.
    • --no-install-project: src/ в builder не копируется, и hatchling не собирает проект пакетом. python -m src находит src через рабочий каталог /app.
  • Версии закреплены: тег@sha256:<digest индекса>. Тег с патч-версией (python:3.12.14-slim-trixie) показывает версию, digest индекса (не манифеста одной платформы) даёт повторяемость и работает на arm64 и amd64. Digest брать из docker buildx imagetools inspect <тег>, строка Digest: в начале вывода. Не latest и не 3.12-slim. uv — COPY --from=ghcr.io/astral-sh/uv:<версия>@sha256:... /uv /bin/uv, а не незакреплённый pip install uv. Зависимости — только из lock (--locked): если uv.lock не совпадает с pyproject.toml, сборка падает. Директиву # syntax= не добавлять: это ещё один незакреплённый образ, а встроенный frontend BuildKit и так понимает RUN --mount.
  • Непривилегированный пользователь: системный app с UID/GID 10001 и USER app перед CMD. Код и .venv копируются от root и доступны пользователю только на чтение.
  • CMD в exec-форме: ["python", "-m", "src"]. Тогда сервер — PID 1 и сам получает SIGTERM. Не sh -c "... && ..." и не uv run: это лишний процесс между docker и сервером.
  • ENV APP__RUN_MODE=docker PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1, EXPOSE 8080.
  • HEALTHCHECK на /health/ready через python -c "import urllib.request; ..." (curl в slim нет) с явными --interval, --timeout, --start-period и --start-interval=1s: без него первая проверка идёт только через interval, и контейнер становится healthy не раньше 10 с. Порт — APP__PORT из окружения, по умолчанию 8080. Healthcheck живёт только в образе: он нужен и без compose (стенд bench/), а compose берёт его из образа и не дублирует.
  • В образ не попадают .env, config.toml, секреты, tests/, student-tests/, contracts/, evidence/, .claude/, openspec/, .venv/. Отличие от bp_proxies: там config.toml копируется в образ, здесь нельзя. Чистый clone его не содержит, и сборка упала бы, а Dockerfile.example (п. 6) запрещает класть конфиг и секреты в образ. Конфигурация приходит на старте: config.toml монтируется read-only в /app/config.toml, переменные — environment compose. Это согласовано с преподавателем 2026-09-29 как выполнение README лабы 1, п. 3 и Dockerfile.example, п. 6 (AGENTS.md, «Согласования с преподавателем»). Что где лежит — settings.md.
  • Миграции едут вместе с образом: migrations/ и alembic.ini копируются в runtime, и миграционный сервис compose запускает тот же образ с другой командой (migrations.md). .dockerignore их не исключает.

.dockerignore

Файл из skeleton дополнять, а не заменять: config.toml, .claude, openspec, tests, student-tests, contracts, infra, *.md, Makefile. .dockerignore не заменяет явный COPY только нужного.

Паттерн без **/ действует только в корне контекста: __pycache__ из skeleton не исключает src/**/__pycache__, и .pyc хоста попадали в образ. Для вложенных путей — **/__pycache__, **/*.py[cod], **/.DS_Store.

Проверка сборки «из чистого clone»

Без коммита и временного каталога: контекст — ровно файлы будущего clone (отслеживаемые и новые неигнорируемые):

git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t mtusi-messenger:lab3 -

.env, config.toml и .venv в него не попадают по .gitignore. Перед PR — ещё и настоящий git clone.

docker-compose.yml

  • Имя проекта — name: mtusi-lab3, образ — mtusi-messenger:lab3. Имя проекта задаёт имена volume: с прежним mtusi-lab2 стенд этой лабы подключился бы к данным второй лабы, а make wipe_data их удалил бы. Имя меняется в каждой новой лабе.

  • Сервис api: build: .; с лабы 3 без ports и без container_name, реплик ${API_REPLICAS:-2}, наружу только LB (balancer.md). До лабы 3 порт был "127.0.0.1:${APP_OUT_PORT:-8080}:${APP__PORT:-8080}"; теперь эта строка — у сервиса haproxy. environment собирается из якорей: x-db-env (APP__RUN_MODE: docker, DATABASE__* из переменных POSTGRES_*) и x-cache-env (CACHE__* из VALKEY_*), у api — оба через <<: [*db-env, *cache-env] плюс APP__PORT (settings.md, «Консоль и docker»). У migrate — только x-db-env: пароль Valkey ему не нужен; haproxy получает только API_PORT (секреты только там, где нужны, рубрика «4»). Healthcheck образа проверяет APP__PORT; stop_grace_period: 10s; restart: unless-stopped; лимиты CPU/RAM (deploy.resources.limits) у всех сервисов — override стендов (bench/) задаёт лимиты в той же форме: cpus / mem_limit рядом с ними compose не принимает. Имена переменных в .env — settings.md, «Имена в .env».

  • Литералов адреса и порта Postgres в compose нет: POSTGRES_HOST становится алиасом сервиса в сети, POSTGRES_PORT — портом самого сервера через PGPORT (его же берут pg_isready и psql в контейнере). Литерал — только адрес публикации 127.0.0.1: это требование безопасности, а не параметр.

  • config.toml — только длинной записью, иначе при отсутствии файла Docker молча создаст на хосте каталог config.toml/, и приложение упадёт на чтении настроек (проверено):

    volumes:
      - type: bind
        source: ./config.toml
        target: /app/config.toml
        read_only: true
        bind:
          create_host_path: false
    

    Без файла compose сразу падает с bind source path does not exist. Поэтому make run_docker зависит от env_setup: недостающие .env и config.toml создаются из шаблонов, существующие не трогаются. Голый docker compose up без файла по-прежнему падает. Голый docker run монтирует его так же строго — --mount type=bind,src="$PWD/config.toml",dst=/app/config.toml,readonly, а не -v. Сам файл необязателен: без него приложение стартует на дефолтах.

  • Смонтированный файл должен читаться непривилегированным пользователем контейнера. На Docker Desktop права хоста не мешают, на Linux нужен режим 644 или совпадающий uid.

  • Новая переменная контейнера — строка в .env.example и в environment сервиса.

  • С лабы 2 compose — основной запуск стенда: API без Postgres запросы не обслуживает. Проверка и запуск — по README: docker compose --env-file .env config --quiet, затем up -d --build, ожидание /health/ready. Роли лабы 3 — load_balancer (HAProxy), api × ≥2, postgres и valkey (contracts/infrastructure.json: Redis/Valkey необязателен, у нас остаётся кэшем). compose.example.yaml — лишь список ролей, стенд — свой docker-compose.yml (compose находит его сам, как и compose.yaml).

  • Образы зависимостей закреплены так же, как базовый: тег с патч-версией и digest индекса (postgres:18.6-trixie@sha256:...), не postgres:18 и не latest. Точка монтирования volume — из Config.Volumes образа: у Postgres 18 это /var/lib/postgresql, а не /var/lib/postgresql/data, как у 17.

  • У каждой зависимости свой healthcheck, API ждёт depends_on: condition: service_healthy. У Postgres — pg_isready -h 127.0.0.1 по TCP: при инициализации образ поднимает временный сервер только на сокете, и проверка через сокет сказала бы «готов» раньше времени. Миграции — отдельный одноразовый сервис на образе API (pull_policy: never, образ собирает api), API ждёт его service_completed_successfully.

  • Данные — именованные volumes. make down и скрипты их не удаляют; удаление учебных данных — отдельная явная команда в REPORT.md.

  • Postgres наружу — только 127.0.0.1:${POSTGRES_OUT_PORT}, для console-режима. Пароль — POSTGRES_PASSWORD в .env, в приложение мостом (settings.md).

  • Valkey (сервис valkey, кэш карточек чатов): тот же пин тега с патч-версией и digest индекса, restart: unless-stopped, healthcheck, api ждёт service_healthy. Отличия от Postgres:

    • volume нет: persistence выключен в infra/valkey/valkey.conf (save "", appendonly no), кэш после рестарта пуст, а данные — в Postgres. Если бы в Valkey жили сессии, persistence был бы обязателен: без него рестарт стёр бы их, и make test-persistence упал бы;
    • пароль — VALKEY_PASSWORD в .env, в контейнер — переменной окружения. Сервер получает его в command через sh -c из переменной контейнера (--requirepass "$$VALKEY_PASSWORD"), в compose он не литерал. Запуск — exec docker-entrypoint.sh valkey-server ...: с sh первым аргументом entrypoint образа не сбрасывает root, а так сервер работает от пользователя valkey;
    • healthcheck — valkey-cli ping с паролем из VALKEYCLI_AUTH (без -a в команде): PONG только после AUTH, и проверка ловит неверный пароль;
    • порт сервера — VALKEY_PORT (--port), алиас в сети — VALKEY_HOST, публикация — 127.0.0.1:${VALKEY_OUT_PORT}, как у Postgres.
  • Конфигурации сервисов (valkey.conf, при необходимости postgresql.conf) — в infra/<сервис>/, монтируются read-only длинной записью с create_host_path: false (infra/README.md). В REPORT.md — таблица роль → сервис → версия/digest → healthcheck → volume → порт → способ передачи credentials.

scripts/restart.sh

Hook для make test-persistence ACTION_SCRIPT=scripts/restart.sh (tests/README.md), по образцу scripts/restart.example.sh.

  • Перезапускает все реплики API, LB и все используемые хранилища: Postgres и Valkey. Volumes, схему и данные сохраняет: без down -v, FLUSHALL, повторного seed и изменения тестовых данных. Кэш Valkey после рестарта пуст сам: persistence у него выключен.
  • Порядок: stop haproxy api → restart postgres valkey → up -d --wait postgres valkey (те же контейнеры, ожидание healthcheck) → start api haproxy. start api запускает и зависимость migrate: повторный прогон миграций — no-op. Число реплик не меняется: start поднимает те же контейнеры, а не масштабирует (реплику, остановленную stop-one.sh, тоже).
  • #!/bin/sh, set -eu, исполняемый бит в git (chmod +x, git update-index --chmod=+x). Возвращает 0 только после действия, укладывается в 90 с. Готовность ждёт сам тест. Секреты не печатает.
  • Успех теста не доказывает, что БД действительно перезапускалась. В evidence/ — состояние контейнеров до и после (docker compose ps, StartedAt из docker inspect).

Дальше

Реплики, HAProxy, scripts/stop-one.sh, поочерёдная замена, лимиты и пулы — balancer.md.