10 KiB
Запуск и эксплуатация решения
Решение находится в ветке 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. Секреты можно сохранить, чтобы новая пустая БД инициализировалась с прежним локальным паролем. Резервные копии в лабораторной не реализованы.