awg-dash/docs/adr/007-embedded-web-server.md

007. Web-сервер: встроенный uvicorn, без nginx

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

Контекст

UI — SPA, API — REST и WebSocket, всё в одном контейнере. Нагрузка: LAN, единичный пользователь. Установка должна быть в одну команду docker run без дополнительных контейнеров.

Решение

Один uvicorn-процесс awg-api отдаёт и API, и собранную статику UI, и WebSocket. Сборка UI выполняется на этапе билда образа и попадает в ui/dist. Закладывается совместимость с внешним reverse-proxy: поддержка base-path и заголовков X-Forwarded-*, без обязательной настройки хоста.

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

• nginx в образе — плюс к размеру и к конфигу, преимуществ при такой нагрузке нет.
• Отдельный контейнер для UI — нарушает требование единого образа.

Последствия

• Заголовки кэширования статики и index.html настраиваются в FastAPI (иначе UI кэшируется после обновления).
• WebSocket идёт через тот же порт: учитывается при настройке reverse-proxy в runbook (#45).
• Docker HEALTHCHECK опирается на /api/v1/health того же процесса (#31).