Deployment API, Swagger и документации

По решению на звонке 04.09.2026 KarmaCode разворачивается на отдельном сервере, выделенном только этому проекту, в инфраструктурном аккаунте команды разработки. У заказчика собственной инфраструктуры пока нет. В разговоре упоминался Timeweb и ориентир около 1 500 ₽ в месяц; provider и сумма являются коммерческими ориентирами и требуют отдельного подтверждения, а не hardcode в инфраструктуре.

Проекты других заказчиков не размещаются на этом Docker host. Compose project names, каталоги, volumes и networks всё равно остаются изолированными между API и документацией KarmaCode. В будущем deployment можно перенести на сервер заказчика после предоставления доступа и согласованного плана миграции.

Топология

Публичный компонент	Внутренний сервис	Default host port	URL path
Product docs	karmacode-docs/docs	8080	/
REST API	karmacode-api/gateway	8081	/api/v1/*
Swagger UI	karmacode-api/gateway	8081	/swagger/
OpenAPI JSON	karmacode-api/gateway	8081	/swagger/openapi.json

PostgreSQL доступен только сервисам Compose-проекта karmacode-api и не публикует host port. Nginx завершает внутренний HTTP, ставит proxy headers/request ID и проверяет доступность Express через /healthz. TLS и домены завершает reverse proxy на выделенном сервере.

Production releases хранятся раздельно:

/opt/karmacode/
├── api/
│   ├── current -> releases/<commit-sha>
│   ├── releases/<commit-sha>/.env
│   └── shared/app.env
├── docs/
│   ├── current -> releases/<commit-sha>
│   └── releases/<commit-sha>/
└── shared/ephemeris/

API workflow применяет Prisma migrations отдельным одноразовым контейнером до обновления API, ждёт health checks API/nginx и проверяет публикацию OpenAPI. После успешного переключения current production env копируется в current/.env с правами 0600. Полная настройка GitHub variables, secrets, reverse proxy и локальная команда проверки приведены в операционном файле infra/api/README.md.