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>
16 KiB
paths
| paths | |||||
|---|---|---|---|---|---|
|
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.
- Оба stage — на одном базовом образе:
- Версии закреплены:
тег@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, переменные —environmentcompose. Это согласовано с преподавателем 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.
- volume нет: persistence выключен в
-
Конфигурации сервисов (
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.