Understand, operate, and evolve a unified production system built with Docker Compose (control-plane services + optional external nodes + monitoring). Use when editing core project files, managing deployment, architecture, telemetry, healthchecks, API integrations, rollout, rollback, or troubleshooting across services.
Editing any file in the main project root
Working with:
docker-compose.yml, docker-compose.observability.ymlmanage.shbackend/ (admin-api FastAPI)frontend/admin/, frontend/miniapp/bot/ (Telegram, aiogram)node-agent/config/ (caddy, monitoring, redis)Questions about:
The system follows a Control Plane / Data Plane / Observability separation.
Core business logic and orchestration:
External systems must be treated as black boxes unless explicitly defined otherwise.
Work step-by-step. Every change must:
No “big bang” refactors.
Each sprint must:
No speculative architecture changes.
.env or runtime injection.Every service must have:
Never ship services without health monitoring.
Before migrations or rollouts:
| Component | Role |
|---|---|
| admin-api | FastAPI control-plane API (backend/) |
| postgres | Primary data store |
| redis | FSM, rate limit, queues, ephemeral state |
| reverse-proxy | Caddy TLS + static frontends (docker/reverse-proxy/) |
| telegram-vpn-bot | Sales gateway, payments (bot/) |
| node-agent | Optional; per-node reconciler (node-agent/) |
| monitoring | Optional profile: Prometheus, Loki, Grafana, etc. (config/monitoring/) |
Use manage.sh as the single operational interface. Key commands (see README.md):
config / config-validate – validate and render configurationbuild / build-admin / build-webapp – build imagesup-core – start admin-api, postgres, redis, reverse-proxy, botup-monitoring – Prometheus, Loki, Grafana, etc. (profile monitoring)bootstrap – core + migrate + seed + seed-agent-server + node-agent (agent mode)up-agent – start node-agent (profile agent)migrate – run DB migrations; seed / seed-agent-server – seed dataserver:verify / server:sync / server:reconcile / server:drift – server opsdevice:reissue – reissue device configcheck – quality gate (ruff, pytest, frontend lint/typecheck/test/build)verify – full gate (migrate integrity, config-validate)smoke-staging – end-to-end validationbackup-db – Postgres backup to backups/postgres/openapi – export OpenAPI to openapi/openapi.yamlsupport-bundle – collect logs, manifest for supportps / logs – compose status and logsRaw docker commands should not be default operational advice.
Observability must work without modifying external nodes unless explicitly permitted.
Use service DNS names (never localhost inside containers)
Implement:
Never assume zero network failure.
If project includes admin UI:
Admin panel must always answer:
Rollback must always be defined before rollout.
When suggesting changes:
No architectural changes without stabilization.
This skill treats every project as:
The goal is not just “it works”. The goal is: **it survives growth, scale, failure, and operator mistakes.**37:["$","$L40",null,{"content":"$41","frontMatter":{"name":"vpn-suite","description":"Understand, operate, and evolve a unified production system built with Docker Compose (control-plane services + optional external nodes + monitoring). Use when editing core project files, managing deployment, architecture, telemetry, healthchecks, API integrations, rollout, rollback, or troubleshooting across services."}}]