awg-dash/deploy/dev-stand.md

dev/staging стенд awg-dash — runbook

Задача #21 (эпик #15). Стенд для локальной разработки и проверки acceptance criteria до появления staging-окружения.

• Docker-хост: 192.168.1.147 (ssh root@192.168.1.147), Docker 29.4.x + compose v5.
• Каталог состояния: /opt/awg-dash-dev/{config,data} (bind mount → /config, /data).
• Compose project: awg-dash-dev (изолирован от PoC-контейнеров amneziawg-client).
• Хост-порт приложения: 8180 (AWG_DASH_PORT), внутри контейнера — 8080. Порт 8080 на dev-хосте занят другим сервисом (drawio), поэтому проброс нестандартный.

Быстрый старт

# на Docker-хосте, из корня репозитория
export AWG_DASH_HOST_DIR=/opt/awg-dash-dev
make dev-up            # docker compose up -d --build (проект awg-dash-dev)
make dev-verify        # проверка AC: health 200 + состояние переживает restart
curl -fsS http://127.0.0.1:8180/api/v1/health
make dev-logs          # логи контейнера
make dev-down          # остановить (каталоги состояния сохраняются)

dev-up добавляет --build, когда в дереве есть deploy/Dockerfile (после мержа #18). Если у хоста нет сети/DNS для docker build (офлайн-стенд, CI без прокси), сборку нужно пропустить — образ awg-dash:dev уже должен существовать:

make dev-up DEV_SKIP_BUILD=1   # up -d --no-build — использовать готовый образ
make dev-up DEV_UP_BUILD=      # вообще не передавать флаги сборки

До реализации FastAPI-каркаса (#31) /api/v1/health не отвечает — контейнер работает как агент и помечается unhealthy. Чтобы проверить плумбинг стенда (порт, healthcheck, тома, restart) до #31, используйте health-заглушку:

make dev-up-stub       # + deploy/docker-compose.stub.yml (DEV-ONLY, api_stub.py)
make dev-verify-stub   # AC-1 проходит на заглушке, в отчёте api=stub

Заглушка отвечает {"status":"ok","stub":true,...} только на /api/v1/health и никогда не должна использоваться в staging/prod.

Проверка AC (#21)

AC	Команда	Ожидание
AC-1: health 200	curl -fsS -o /dev/null -w '%{http_code}' http://127.0.0.1:8180/api/v1/health	200 (после мержа #31; до него — заглушка через dev-verify-stub)
AC-2: состояние переживает restart	make dev-verify	маркеры в /config и /data совпадают до и после docker compose restart и --force-recreate
AC-3: netns + мок-endpoint	make test-netns	8/8 тестов, netns awgt21-{client,gw,uplink} создаются и сносятся

deploy/verify-dev-stand.sh (за make dev-verify) печатает отчёт и возвращает:

Код	Значение
0	AC-1 и AC-2 выполнены
1	регрессия стенда (health не 200 с заглушкой, состояние не сохранилось)
2	AC-1 заблокирован: API (#31) ещё не реализован, стенд при этом поднят
3	заблокировано окружением: нет docker/compose или compose-файлов

Состав стенда

Файл	Назначение
docker-compose.dev.yml	приложение: порт 8080 (наружу ${AWG_DASH_PORT:-8180}), bind mount /config /data, healthcheck, NET_ADMIN/NET_RAW/SYS_MODULE, /dev/net/tun
docker-compose.stub.yml	DEV-ONLY оверрайд: health-заглушка до #31 (api_stub.py)
docker-compose.test.yml	тестовый стенд: привилегированный netns-раннер + app для API-тестов
api_stub.py	минимальный HTTP-сервер /api/v1/health (только dev)
verify-dev-stand.sh	проверка AC на Docker-хосте + JSON-отчёт
../tests/netns/	netns-харнесс: топология client/gw/uplink + мок WireGuard-endpoint

Переменные окружения

Переменная	По умолчанию	Назначение
AWG_DASH_PORT	8180	хост-порт приложения
AWG_DASH_HOST_DIR	/opt/awg-dash-dev	каталог состояния на хосте
AWG_DASH_IMAGE	awg-dash:dev	имя образа (build или pull)
AWG_DASH_DOCKERFILE	deploy/Dockerfile	путь к Dockerfile для build
COMPOSE_PROJECT_NAME	awg-dash-dev	изоляция от других стендов
AWG_LOG_LEVEL	info	уровень логирования приложения
DEV_SKIP_BUILD	—	1 → make dev-up выполняет up -d --no-build (образ уже собран)
DEV_UP_BUILD	авто	переопределение флагов сборки (--build, пусто, --no-build)
AWG_NS_EXEC_MODE	auto	режим входа в netns: `auto
NETNS_EXEC_MODE	auto	make-алиас AWG_NS_EXEC_MODE (приоритет у AWG_NS_EXEC_MODE)

Зависимости

Зависимость	Состояние	Влияние на стенд
#16 (каркас репо, Makefile)	PR #47	нужен Makefile, requirements.txt, deploy/
#18 (образ, entrypoint)	PR #49	нужен deploy/Dockerfile для --build
#31 (каркас FastAPI, /api/v1/health)	Sprint 2	без него AC-1 выполняется только с заглушкой
#17 (CI-пайплайн)	Sprint 0	гейты для пайплайна: bash tests/netns/ci.sh (коды 0/1/3/4), make test-manifests, make test-deploy, make lint-shell

Откат и уборка

make dev-down                       # остановить контейнеры проекта awg-dash-dev
make dev-reset                      # down --remove-orphans (состояние сохраняется)
docker image rm awg-dash:dev        # откатить образ (пересобрать из предыдущего коммита)
du -sh /opt/awg-dash-dev            # состояние стенда

Перед откатом образа проверьте проект: docker compose -p awg-dash-dev ls. Состояние (/opt/awg-dash-dev) не удаляется автоматически — это осознанно: там конфиги туннеля (/config/awg0.conf). Удаляйте вручную и только после бэкапа.

Pitfalls

• Порт 8080 занят на dev-хосте — наружу публикуется 8180. Меняйте AWG_DASH_PORT.
• /dev/net/tun обязателен: без него entrypoint падает (fail '/dev/net/tun не проброшен').
• Права на каталоги состояния: entrypoint делает chown awg:awg /config /data; каталоги создаются на хосте от root — не меняйте владельца на хосте вручную.
• docker compose restart сохраняет тома; down -v — нет. Никогда не используйте down -v на этом стенде: это удалит /config и /data.
• Заглушка api_stub.py — только dev: она отвечает 200 на /api/v1/health и маскирует отсутствие API. Не включайте docker-compose.stub.yml в staging.
• netns-стенд вне Docker требует root: make test-netns вернёт код 3, если нет CAP_NET_ADMIN/CAP_SYS_ADMIN (например, в непривилегированном CI-раннере).
• netns в контейнере (make test-netns-ci, bash tests/netns/ci.sh): ip netns exec падает (mount of /sys failed), харнесс сам переходит на nsenter; контракт кодов 0/1/3/4 действует на уровне контейнера. make возвращает 2 на любом провале — в CI вызывайте bash tests/netns/ci.sh, иначе ветки 3 и 4 неразличимы (#56).
• --build без сети: после мержа #18 dev-up собирает образ; если на хосте нет DNS/доступа к registry, используйте DEV_SKIP_BUILD=1 (готовый awg-dash:dev).