Files
mtusi2026lab3/RUNBOOK.md
T

10 KiB
Raw Blame History

Запуск и эксплуатация решения

Решение находится в ветке solution/bpi2301-chernenko. Исходный README с заданием не изменён. Предыдущая реализация lab2 не была предоставлена: её обязательный минимум написан в src/ заново по контракту текущего skeleton, без копирования чужого решения. Основной маршрут всех бизнес-проверок — HAProxy.

Требования

  • Docker Engine с Compose v2+ или Docker Desktop в режиме Linux containers.
  • Python 3.9+ на host для bootstrap и orchestration; проверено с Python 3.12.10.
  • Свободный TCP-порт 8080 на loopback; при конфликте изменить PUBLIC_PORT в .env.
  • Доступ к Docker Hub и PyPI при первой сборке; достаточно примерно 8 GiB RAM для Docker VM, проверенная машина предоставляла 16 логических CPU.
  • Для hooks на Linux файлы scripts/*.sh должны быть executable; Git хранит этот бит, а .gitattributes задаёт LF. При ручном копировании выполнить chmod +x scripts/restart.sh scripts/stop-one.sh.

GNU Make и зависимости Python на host не нужны при использовании контейнера tester. Он содержит Make, Python и инструменты проверки. Docker CLI нужен внутри него для явных операторских hooks.

Чистый запуск

Скачать ветку решения из fork после её публикации:

git clone --branch solution/bpi2301-chernenko https://gitea.privcloud.tech/quzzqq/mtusi2026lab3.git
cd mtusi2026lab3
python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build
docker compose build tester
docker compose run --rm -T tester python scripts/wait_ready.py
docker compose run --rm -T tester python scripts/demo.py
docker compose run --rm -T tester make check validate test
docker compose run --rm -T tester python student-tests/integration.py

На Windows заменить python3 на py -3.12; дальнейшие команды Docker одинаковы. Если решение получено локально до push, перейти в уже склонированный каталог и начать с bootstrap. .env создаётся из .env.example, секреты — случайно в secrets/. Bootstrap не перезаписывает существующие файлы; не удалять их при обычном рестарте, иначе пароль БД и ключ курсоров могут перестать совпадать.

Compose сначала ждёт PostgreSQL, запускает отдельный migrate, затем API и LB. Успешно завершившийся migrate со статусом Exited (0) — нормальное состояние. Он проверяет таблицу schema_migrations, применяет отсутствующие SQL-файлы одной транзакцией под advisory lock и не меняет существующие пользовательские данные. Реплики API миграций не выполняют.

Все проверки

python3 scripts/acceptance.py
python3 scripts/extra_checks.py
python3 scripts/run_experiments.py rolling
python3 scripts/run_experiments.py scaling --duration 20 --warmup 5 --repeats 3
docker compose run --rm -T tester python scripts/plot_results.py
python3 scripts/write_research.py

На Windows использовать py -3.12 -X utf8 вместо python3: публичный skeleton читает UTF-8 без явного encoding и требует UTF-8 mode в Windows. Команды последовательно изменяют только локальный учебный стенд. Не запускать acceptance, rolling, extra_checks и scaling одновременно: эксперименты специально меняют количество реплик, CPU-квоты и доступность БД. scaling и rolling восстанавливают две API по 0.5 CPU/256 MiB и DB 1 CPU в блоке finally. Если host-процесс принудительно убит, восстановить вручную:

docker compose up -d --scale api=2
docker compose run --rm -T tester python scripts/wait_ready.py
docker compose run --rm -T tester python scripts/demo.py

extra_checks кратко включает TTL=2 секунды, затем возвращает TTL из .env, отдельно останавливает PostgreSQL и проверяет live/ready внутри Docker-сети. Это диагностический внутренний запрос, порты API наружу не публикуются. Публичные проверки и исследование идут через LB.

Одиночные штатные сценарии:

docker compose run --rm -T tester make test-persistence ACTION_SCRIPT=scripts/restart.sh
docker compose run --rm -T tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose ps --all
docker compose start api
docker compose run --rm -T tester python scripts/demo.py

stop-one сопоставляет переданный тестом TARGET_INSTANCE_ID с hostname реального контейнера в этом Compose project, останавливает только его и оставляет остановленным. restart останавливает API, LB и единственную PostgreSQL, содержащую также сессии, затем запускает те же контейнеры без удаления volume. Для evidence отдельный вызов того же hook сохраняет StartedAt/FinishedAt.

Runner — одноразовый операторский инструмент профиля tools, не часть публичного сервиса. Ему передаётся Docker socket для hooks; это административный доступ к локальному Docker-host. Запускать только для доверенного кода этого учебного проекта. В CI используются отдельный disposable runner и штатный Docker-host CI; внешние секреты и общий production Docker-host не подключаются.

Настройки

Эффективные переменные .env.example:

  • API_REPLICAS: начальное число реплик, по умолчанию 2; HAProxy имеет 8 слотов.
  • API_CPUS, API_MEMORY: лимит одной API-реплики, 0.5 CPU и 256 MiB.
  • DB_CPUS: лимит PostgreSQL, 1 CPU; память БД фиксирована в Compose — 512 MiB.
  • DB_POOL_SIZE: максимум соединений каждой API, по умолчанию 4.
  • SESSION_TTL_SECONDS: срок сессии, 3600 s; для smoke/persistence нужен >=300 s.
  • IDEMPOTENCY_TTL_SECONDS: >=86400 s; меньший TTL приложение отвергает.
  • PUBLIC_PORT: опубликованный порт HAProxy, по умолчанию 8080 только на 127.0.0.1.

Адрес API внутри контейнера фиксирован 0.0.0.0:8080 командой Dockerfile; SESSION_STORE не нужен, хранилище явно PostgreSQL. Неиспользуемые предложения исходного .env.example удалены, чтобы они не выглядели рабочими настройками. DATABASE_URL_FILE и CURSOR_KEY_FILE задаются в Compose как фиксированные пути к /run/secrets/database_url и /run/secrets/cursor_key, а не как значения секретов в environment. PostgreSQL получает только db_password, мигратор — database_url, API — database_url и cursor_key, балансировщик секретов не получает.

Во время исследования контроллер меняет CPU/RAM API через Compose, а CPU DB через docker update --cpus, сохраняя тот же процесс, БД и volume. Эти квоты фиксируются через inspect в *.resources.json, а не предполагаются по .env.

Обновление и остановка

# Обычная остановка с сохранением данных и конфигурации
docker compose down
# Повторный запуск с тем же volume и secrets
docker compose up -d

Поочерёдная замена под нагрузкой реализована в run_experiments.py rolling: добавляется готовая третья реплика, две исходные по очереди заменяются, в конце остаются две с новыми ID. Это эквивалент rolling replacement той же версии образа, без изменения схемы и бизнес-кода. При выпуске другой версии образа сначала проверить обратную совместимость; обычное up --force-recreate api само по себе не является гарантированным rolling update всех реплик.

Начальная миграция совместима с запущенными репликами после её применения. Destructive schema changes в этом эксперименте не выполнялись и не доказаны. Для будущих версий нужны additive expand/contract-миграции с отдельным job.

Только для намеренного удаления ВСЕХ синтетических данных данного стенда:

docker compose down --volumes

Эта команда не используется ни одним тестом или hook. Секреты можно сохранить, чтобы новая пустая БД инициализировалась с прежним локальным паролем. Резервные копии в лабораторной не реализованы.