awg-dash/docs/adr/002-single-image-modular-monolith.md

002. Модульный монолит в одном образе, два процесса

• Статус: принято
• Контекст/issue: #15, #18

Контекст

ТЗ требует единый Docker-образ с минимальными параметрами запуска. Часть операций требует root (интерфейс awg, iptables/ipset, dnsmasq на порту 53), а веб-часть должна быть скомпрометирована безопасно — без root.

Решение

Один образ, два процесса под супервизором deploy/entrypoint.sh:

Процесс	Права	Ответственность
awg-agent	root, NET_ADMIN	туннель, netfilter, routing, dnsmasq, метрики
awg-api	непривилегированный	FastAPI, REST/WS, статика UI

Обмен — unix-socket /run/awg/agent.sock, общее состояние — SQLite в /data и конфиги в /config.

Альтернативы

• Микросервисы (отдельные контейнеры agent/api/dns) — общая сеть, координация и дублирование привилегий; выгода масштабирования на одном шлюзе отсутствует.
• Один процесс под root — проще, но даёт веб-слою полные права; неприемлемо.

Последствия

• Супервизор обязан пробрасывать сигналы и коды выхода, иначе Docker не заметит падения процесса.
• Права на unix-socket входят в security-проверки (#44).
• Перезапуск API не разрывает туннель.