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

KarmaCode разворачивается на общем Docker host рядом с другим проектом, но не использует его контейнеры, volumes или Docker networks. Изоляция обеспечивается разными Compose project names, каталогами и host ports; пользовательские подсети и статические IP не создаются.

Топология

Публичный компонент	Внутренний сервис	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.