# Запуск на ноутбуке с Windows и сценарий защиты ЛР 3 Команды — в **PowerShell** из папки проекта (где лежит `compose.yaml`). Переменные `$env:...` действуют до закрытия окна. ## 1. Что установить один раз | Программа | Зачем | Важно | | --- | --- | --- | | [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\*.cmd` запускают `.sh`-хуки | | [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, HAProxy, API | backend WSL 2, виртуализация в BIOS; для трека 1 в Settings → Resources дать **8 CPU** | | [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные и свои тесты, скрипты замеров | галочка **Add python.exe to PATH** | | GNU make (необязательно) | `make check/test/test-failover …` | `winget install ezwinports.make`, затем **новое** окно PowerShell. Рецептам Makefile нужен `sh`: в каждом окне PowerShell один раз `$env:Path += ";C:\Program Files\Git\usr\bin"` (или запускать make из Git Bash). Без make те же команды есть в таблице REPORT.md | Проверка: ```powershell git --version; docker version --format '{{.Server.Version}}'; docker compose version; python --version; make --version ``` ## 2. Развернуть проект (дома, заранее — нужен интернет) ```powershell git clone https://gitea.privcloud.tech/wfa/mtusi2026lab3 mtusi2026lab3 cd mtusi2026lab3 git checkout solution/bvt2302-bodanyuk python scripts\init_secrets.py # случайные пароли в .\secrets (не в Git) Copy-Item .env.example .env docker compose --env-file .env config --quiet # конфигурация собирается без ошибок docker compose --env-file .env up -d --build --wait ``` Первый запуск качает образы (~800 МБ) и собирает API — 3–10 минут. Команда завершается, когда postgres, valkey, обе реплики api и lb в состоянии `healthy`, а `migrate` завершился с кодом 0. Окружение для своих тестов и скриптов (один раз): ```powershell python -m venv .venv .venv\Scripts\python -m pip install --require-hashes --no-deps -r requirements.txt .venv\Scripts\python -m pip install -r requirements-test.txt -r requirements-dev.txt $env:PYTHONUTF8 = "1" # публичные тесты читают UTF-8 JSON ``` Проверка в браузере: http://127.0.0.1:8080/health/ready → `{"status":"ok"}`; Swagger — http://127.0.0.1:8080/docs; состояние балансировщика (какие реплики UP/DOWN) — http://127.0.0.1:8404/. ## 3. Перед защитой (в аудитории) ```powershell cd mtusi2026lab3 $env:PYTHONUTF8 = "1" $env:Path += ";C:\Program Files\Git\usr\bin" # sh для рецептов Makefile docker compose up -d --wait # если стенд был остановлен make check test PYTHON=python # или: python scripts\check_contract.py; python tests\smoke.py python scripts\lbctl.py status # обе реплики UP ``` ## 4. Сценарий защиты из README — по шагам **Шаг 1. ≥ 2 разных `X-Instance-Id` через LB с одной сессией.** ```powershell python scripts\lbctl.py replicas # контейнеры api: имя, X-Instance-Id (= hostname), PID, IP # Один пользователь, один токен, 6 запросов подряд через LB — номера реплик чередуются: $u = "demo_" + (Get-Random); $p = "Demo-password-123" Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/users -ContentType 'application/json' -Body (@{username=$u; display_name='Демо'; password=$p} | ConvertTo-Json) $basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${u}:${p}")) $t = (Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/v1/auth/sessions -Headers @{Authorization="Basic $basic"}).token 1..6 | ForEach-Object { (Invoke-WebRequest http://127.0.0.1:8080/api/v1/users/me -Headers @{Authorization="Bearer $t"} -UseBasicParsing).Headers['X-Instance-Id'] } ``` Повторный вход не нужен: сессия лежит в общем Valkey. То же автоматически: `.venv\Scripts\python -m pytest student-tests\test_balancing.py -k one_session -v`. **Шаг 2. Отказ реплики публичным тестом.** ```powershell make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python # без make: python tests\resilience.py --mode failover --action-script scripts\stop-one.cmd ``` Тест сам выбирает реплику, обслужившую его первое сообщение, и передаёт её `X-Instance-Id` хуку. Хук останавливает именно этот контейнер и оставляет его остановленным. Вариант «падение процесса» — `$env:STOP_MODE = "kill"` перед командой (SIGKILL), вернуть — `Remove-Item Env:STOP_MODE`. **Шаг 3. Показать, какой контейнер действительно остановлен, и повторить для второй.** ```powershell python scripts\lbctl.py replicas # у остановленной: exited, exit_code 0 (stop) или 137 (kill) python scripts\lbctl.py status # её слот в HAProxy — MAINT/DOWN, вторая UP docker compose logs --tail 20 api # drain_started -> shutdown_requested -> stopped у остановленной make restore PYTHON=python # или: & "C:\Program Files\Git\bin\bash.exe" scripts/restore-api.sh; python scripts\lbctl.py wait-up 2 make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python ``` Тест останавливает ту реплику, которая обслужила его первое сообщение, поэтому для второй он может снова выбрать прежнюю. Детерминированно по очереди каждую реплику останавливает серия уровня 4 (~5 мин): `python bench\failover_series.py --output evidence\failover` (stop, kill и pause для каждой реплики, с восстановлением предыдущей). **Шаг 4. Restart всего стенда с сохранением volumes и прежним токеном.** ```powershell make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python python scripts\lbctl.py replicas # у всех api свежий started и новый PID; LB снова видит обе реплики docker compose ps # postgres, valkey, lb — тоже «Up N seconds» ``` **Уровень 4 вживую.** ```powershell # Неготовая, но живая реплика исключается из LB (pg_hba reject и docker network disconnect), ~1 мин: .venv\Scripts\python -m pytest student-tests\test_balancing.py -k not_ready -v -s # Rolling update под нагрузкой (~1,5 мин): новая ревизия на обеих репликах, 0 ошибок python bench\rolling_under_load.py --output evidence\rolling-update # Одновременные повторы с одним ключом через разные реплики: .venv\Scripts\python -m pytest student-tests\test_idempotency.py -k concurrent -v ``` **Трек 1.** Полная серия идёт часы, поэтому на защите — готовые результаты: [evidence/track1/summary.md](../evidence/track1/summary.md) и графики `evidence/track1/*/*/throughput.svg`. Вживую можно показать профиль одной реплики (~2 мин) и одну короткую серию (~6 мин): ```powershell docker compose stop # основной стенд не должен мешать замеру python bench\track1\profile.py --label demo --rate 240 python bench\track1\run.py --series demo --label now --rates 150,250,350 --repeats 1 --config replicas=2,MESSAGE_WRITE_PATH=multi --config replicas=2,MESSAGE_WRITE_PATH=function docker compose up -d --wait # вернуть основной стенд ``` **Все свои тесты** (~8 мин): `.venv\Scripts\python -m pytest student-tests -v`. ## 5. Если что-то пошло не так | Симптом | Что сделать | | --- | --- | | `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту | | `port is already allocated` на 8080/8404 | занято другим стендом (lab2: `docker compose -p mtusi-lab2 stop`) или в `.env` поставить `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405`; тестам — `--base-url http://127.0.0.1:8081` / `$env:BASE_URL` | | `secrets/... not found` при `up` | не выполнен `python scripts\init_secrets.py` | | `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` | | `*.cmd`: «не удаётся найти путь» | Git установлен не в `C:\Program Files\Git` — поправить путь в `scripts\*.cmd` | | `make: command not found` | новое окно PowerShell после установки make или команды без make из REPORT.md | | make: `'test' is not recognized` | в этом окне не добавлен `C:\Program Files\Git\usr\bin` в `$env:Path` (рецептам нужен `sh`) | | после `stop-one` в LB одна реплика | так и задумано; вернуть: `make restore PYTHON=python` | | api `unhealthy` после сна ноутбука | `docker compose restart` и `python scripts\lbctl.py wait-up 2` | | нужно начать с чистого листа | `docker compose down -v` (удаляет учебные данные) → `docker compose up -d --build --wait` | Остановить стенд после защиты: `docker compose down` (данные сохранятся) или `docker compose down -v` (данные удаляются).