SILVER
/
NODEDC_PLATFORM
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

DOCS - DEPLOY: add Ops Agents Gateway handoff

This commit is contained in:
Codex 2026-05-15 00:47:59 +03:00
parent 25d3004cef
commit c99ad80aa7
3 changed files with 461 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@ -22,6 +22,7 @@ Git repo:
Артефакты: Артефакты:
- `docs/CURRENT_INFRA_HANDOFF.md`
- `docs/DISCOVERY_REPORT.md` - `docs/DISCOVERY_REPORT.md`
- `docs/ARCHITECTURE.md` - `docs/ARCHITECTURE.md`
- `docs/AUTH_MODEL.md` - `docs/AUTH_MODEL.md`

456
docs/CURRENT_INFRA_HANDOFF.md Normal file
View File

@ -0,0 +1,456 @@
# NODE.DC current infra handoff
Last updated: 2026-05-15.
This document is the fast context entrypoint for a new engineering chat. Read it first before touching deploy, Synology, Authentik, Launcher, or Tasker.
## Product shape
NODE.DC is intentionally modular. It is not a single monorepo with all products merged into one codebase.
Source-of-truth repositories:
| Module | Responsibility | Local source |
| --- | --- | --- |
| Platform | Infra, Authentik, reverse proxy, Synology deploy scripts, architecture docs | `/Users/dcconstructions/Downloads/mnt/NODEDC/platform` |
| Launcher / Hub | NODE.DC control plane, user/admin UI, access requests, access matrix, Authentik sync | `/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher` |
| Tasker / Operational Core | Plane fork, tasks/workspaces/projects, standalone-capable product module | `/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER` |
| Ops Agents Gateway | Standalone MCP/API router for Tasker operational agents | `/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI` |
Current Git branches:
- Platform: `main`
- Launcher: `main`
- Tasker: `master`
- Ops Agents Gateway: `main`
The modules communicate through HTTP/OIDC/internal APIs. They must remain independently buildable and deployable.
## Ownership boundaries
Do not collapse data into one shared database.
| Area | Owner | Runtime state |
| --- | --- | --- |
| Identity, SSO, OIDC providers | Authentik | Authentik PostgreSQL volume in `nodedc-platform` |
| Clients, users, groups, Launcher access matrix | Launcher | Launcher JSON/runtime storage under `/volume1/docker/nodedc-platform/launcher` |
| Workspaces, projects, issues, comments, files | Tasker | Tasker PostgreSQL + MinIO/RabbitMQ/Redis volumes under `nodedc-tasker` |
Launcher can project access into Tasker, but it must not become the owner of Tasker domain tables. Tasker can run standalone if NODE.DC integration env vars are disabled or pointed elsewhere.
## Synology topology
Current NAS root:
```text
/volume1/docker/nodedc-platform
```
Mounted on macOS as:
```text
/Volumes/docker/nodedc-platform
```
Public domains:
```text
https://id.nodedc.ru -> Authentik
https://hub.nodedc.ru -> Launcher / Hub
https://ops.nodedc.ru -> Tasker / Operational Core
https://ops-agents.nodedc.ru -> Ops Agents Gateway / MCP endpoint
```
Local/NAS check domains used during rollout:
```text
auth.nas.nodedc
launcher.nas.nodedc
task.nas.nodedc
auth.local.nodedc
launcher.local.nodedc
task.local.nodedc
```
### Platform compose project
Compose project:
```text
nodedc-platform
```
Compose file:
```text
/volume1/docker/nodedc-platform/platform/docker-compose.platform-http.yml
```
Source copy:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC/platform/infra/synology/docker-compose.platform-http.yml
```
Main services:
- `reverse-proxy`: Caddy HTTP edge, publishes host port `18080`.
- `launcher`: `nodedc/launcher:local`, serves Hub on container port `5173`.
- `postgresql-authentik`: Authentik PostgreSQL.
- `authentik-server`: Authentik web/server.
- `authentik-worker`: Authentik worker.
Main Docker volumes:
- `authentik-database`
- `authentik-data`
- `authentik-certs`
- `caddy-data`
- `caddy-config`
Launcher bind-mounted runtime state:
```text
/volume1/docker/nodedc-platform/launcher/server-storage -> /app/server/storage
/volume1/docker/nodedc-platform/launcher/uploads -> /app/dist/storage/uploads
/volume1/docker/nodedc-platform/launcher/uploads -> /app/public/storage/uploads
```
These directories must be writable by container user `node` / UID `1000`.
### Tasker compose project
Compose project:
```text
nodedc-tasker
```
NAS runtime/deploy directory:
```text
/volume1/docker/nodedc-platform/tasker/plane-app
```
NAS source/deploy copy:
```text
/volume1/docker/nodedc-platform/tasker/plane-src
```
Repository source:
```text
/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src
```
Repository compose/runtime template:
```text
/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-app/docker-compose.yaml
```
Main services:
- `web`: Tasker frontend, image `nodedc/plane-frontend:ru`.
- `admin`: Tasker admin frontend, image `nodedc/plane-admin:ru`.
- `space`: public/space frontend, image `nodedc/plane-space:ru`.
- `live`: live server, image `nodedc/plane-live:local`.
- `api`: backend API, image `nodedc/plane-backend:local`.
- `worker`, `beat-worker`, `migrator`: backend workers/migrations.
- `plane-db`: PostgreSQL.
- `plane-redis`: Valkey/Redis.
- `plane-mq`: RabbitMQ.
- `plane-minio`: uploads/files.
- `proxy`: Tasker edge proxy, publishes `LISTEN_HTTP_PORT` / current NAS port `18090`.
Main Docker volumes under the `nodedc-tasker` project:
- `nodedc-tasker_pgdata`
- `nodedc-tasker_redisdata`
- `nodedc-tasker_rabbitmq_data`
- `nodedc-tasker_uploads`
- log and proxy volumes from `plane-app/docker-compose.yaml`
NAS-only runtime files currently exist and are intentionally not committed with secrets:
```text
/volume1/docker/nodedc-platform/tasker/plane-app/.env.synology
/volume1/docker/nodedc-platform/tasker/plane-app/docker-compose.synology.override.yml
```
The current override only adds `extra_hosts` entries so Tasker backend containers can resolve `id.nodedc.ru`, `hub.nodedc.ru`, `ops.nodedc.ru`, local domains, NAS domains, and `host.docker.internal` through `host-gateway`.
### Ops Agents Gateway compose project
Compose project:
```text
nodedc-ops-agents
```
Recommended NAS runtime/deploy directory:
```text
/volume1/docker/nodedc-platform/ops-agents
```
Repository source:
```text
/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI
```
Public entrypoint:
```text
https://ops-agents.nodedc.ru
```
Synology reverse proxy should route:
```text
HTTPS ops-agents.nodedc.ru:443 -> HTTP 127.0.0.1:18190
```
Do not use host port `18090` for this module: `18090` is the Tasker proxy port. Gateway container port remains `4100`; host port is controlled by `HOST_PORT=18190`.
Main services:
- `agent-gateway`: NODE.DC Operational Agents Gateway, image built from source by compose.
- `postgres`: Gateway-owned PostgreSQL database for agents, grants, tokens, idempotency, and audit.
Deployment checklist:
```text
/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI/docs/SYNOLOGY_DEPLOY.md
```
## Deploy model
NAS is a deploy target and runtime state holder. It is not the source of truth for code.
Normal direction:
```text
Git repo -> build image / sync deploy files -> Synology compose recreate selected service
```
Do not edit NAS copies as the long-term fix. If an emergency live edit is made on NAS, port it back into the relevant repo before continuing product work.
## Platform / Launcher deploy
From macOS with `/Volumes/docker` mounted:
```bash
cd /Users/dcconstructions/Downloads/mnt/NODEDC/platform
NAS_ROOT=/Volumes/docker/nodedc-platform \
LAUNCHER_REPO=/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher \
./infra/synology/deploy-current.sh
```
The script syncs platform deploy files and prints the Docker commands that must be run on Synology, because Docker there requires interactive `sudo`.
Launcher image build is done from the Launcher repo when frontend/backend code changes:
```bash
cd /volume1/docker/nodedc-platform/launcher/source
sudo /usr/local/bin/docker build --no-cache -t nodedc/launcher:local .
```
Launcher container recreate:
```bash
cd /volume1/docker/nodedc-platform/platform
sudo /usr/local/bin/docker compose \
--env-file /volume1/docker/nodedc-platform/platform/.env.synology \
-f /volume1/docker/nodedc-platform/platform/docker-compose.platform-http.yml \
up -d --force-recreate --no-deps launcher
```
## Tasker deploy
Tasker rebuild script is in the Tasker repo and copied to NAS:
```text
/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/rebuild-nas-legacy.sh
```
Production-style frontend rebuild on NAS:
```bash
cd /volume1/docker/nodedc-platform/tasker/plane-src
BUILD_BACKEND=0 BUILD_WEB=1 BUILD_ADMIN=0 sh rebuild-nas-legacy.sh
```
Admin frontend rebuild:
```bash
cd /volume1/docker/nodedc-platform/tasker/plane-src
BUILD_BACKEND=0 BUILD_WEB=0 BUILD_ADMIN=1 sh rebuild-nas-legacy.sh
```
Combined web/admin rebuild:
```bash
cd /volume1/docker/nodedc-platform/tasker/plane-src
BUILD_BACKEND=0 BUILD_WEB=1 BUILD_ADMIN=1 sh rebuild-nas-legacy.sh
```
The script defaults production frontend links to:
```text
VITE_NODEDC_LAUNCHER_URL=https://hub.nodedc.ru
```
Local/staging can override:
```bash
VITE_NODEDC_LAUNCHER_URL=http://launcher.local.nodedc \
BUILD_BACKEND=0 BUILD_WEB=1 BUILD_ADMIN=0 \
sh rebuild-nas-legacy.sh
```
Manual recreate command used on NAS:
```bash
cd /volume1/docker/nodedc-platform/tasker/plane-app
sudo /usr/local/bin/docker compose -p nodedc-tasker \
--env-file .env.synology \
-f docker-compose.yaml \
-f docker-compose.synology.override.yml \
up -d --no-build --force-recreate web
```
Replace `web` with `admin`, `api`, or another service only when that service image was intentionally rebuilt.
Tasker backend must receive the Gateway internal URL/token before Codex/Ops Agent UI can create agents in production:
```env
PLANE_NODEDC_AGENT_GATEWAY_URL=http://127.0.0.1:18190
PLANE_NODEDC_AGENT_GATEWAY_TOKEN=<same value as NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN>
```
After changing these env vars, rebuild/recreate Tasker backend services: `api`, `worker`, `beat-worker`, and `migrator` when migrations are expected.
## Ops Agents Gateway deploy
From the Gateway repo on Synology or from a synced source copy:
```bash
cd /volume1/docker/nodedc-platform/ops-agents
sudo /usr/local/bin/docker compose --env-file .env -f docker-compose.synology.yml up -d --build
```
Required Synology `.env` values are documented in:
```text
/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI/docs/SYNOLOGY_DEPLOY.md
```
Minimum checks:
```bash
curl -fsS http://127.0.0.1:18190/healthz
curl -fsS http://127.0.0.1:18190/readyz
curl -fsS -i https://ops-agents.nodedc.ru/mcp | head
```
## Backup rules
Platform backup script:
```bash
cd /Users/dcconstructions/Downloads/mnt/NODEDC/platform
NAS_ROOT=/Volumes/docker/nodedc-platform ./infra/synology/backup-current.sh
```
It creates filesystem backups and generates a Synology-side Authentik database dump command.
Tasker safety:
- Frontend-only Tasker rebuilds do not touch Tasker PostgreSQL or MinIO uploads.
- Backend image rebuild is not enough to lose data by itself, but backend migrations can change DB schema.
- Before backend migrations, backup `nodedc-tasker_pgdata` and `nodedc-tasker_uploads`.
- Never run destructive volume commands on NAS production data.
Hard rules:
```text
Never run docker compose down -v on production/staging data.
Never delete nodedc-tasker_* volumes without a verified backup.
Never use docker system prune blindly on the NAS.
Never commit .env.synology or real secrets.
```
## Local development model
The same codebase must support local and production-like runs. Differences must come from env vars and build args, not branches with hardcoded production URLs.
Local target domains:
```text
127.0.0.1 auth.local.nodedc
127.0.0.1 launcher.local.nodedc
127.0.0.1 task.local.nodedc
```
Platform local docs:
```text
/Users/dcconstructions/Downloads/mnt/NODEDC/platform/docs/DEPLOYMENT_LOCAL.md
/Users/dcconstructions/Downloads/mnt/NODEDC/platform/infra/README.md
```
Tasker local/prod integration env contract:
```text
/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/NODEDC_TASKER_DEPLOY_MODEL.md
```
Useful local Tasker frontend build checks:
```bash
cd /Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src
pnpm turbo run build --filter=web
pnpm turbo run build --filter=admin
```
Known current validation note: `admin` typecheck passes. Full `web` typecheck currently has pre-existing upstream/local Plane TypeScript debt unrelated to the NODE.DC logo/deploy baseline work.
## Current docs map
Read these in order:
1. This file: `/Users/dcconstructions/Downloads/mnt/NODEDC/platform/docs/CURRENT_INFRA_HANDOFF.md`
2. Architecture: `/Users/dcconstructions/Downloads/mnt/NODEDC/platform/docs/ARCHITECTURE.md`
3. Synology deploy: `/Users/dcconstructions/Downloads/mnt/NODEDC/platform/infra/synology/README.md`
4. Local deploy: `/Users/dcconstructions/Downloads/mnt/NODEDC/platform/docs/DEPLOYMENT_LOCAL.md`
5. Tasker deploy model: `/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/docs_prod/NODEDC_TASKER_DEPLOY_MODEL.md`
6. Ops Agents Gateway deploy: `/Users/dcconstructions/Downloads/mnt/data/NODEDC_TASKMANAGER_CODEXAPI/docs/SYNOLOGY_DEPLOY.md`
## New-chat bootstrap prompt
Use this when starting a new engineering chat:
```text
We are working on NODE.DC. First read:
/Users/dcconstructions/Downloads/mnt/NODEDC/platform/docs/CURRENT_INFRA_HANDOFF.md
Respect the modular architecture:
- Platform repo owns infra/Synology/Auth/reverse-proxy docs and scripts.
- Launcher repo owns Hub/control-plane.
- Tasker repo owns Plane fork and must remain standalone-capable.
- Ops Agents Gateway repo owns MCP/API routing for external operational agents.
- NAS is deploy target/runtime state, not source of truth.
- Do not touch production volumes destructively.
- Do not commit secrets or .env.synology.
```
## Known follow-up hardening
- Add a sanitized committed Tasker `docker-compose.synology.override.example.yml`.
- Add a Tasker volume backup script equivalent to Platform `backup-current.sh`.
- Add an Ops Agents Gateway backup script for its Postgres volume/dump.
- Add a single smoke-check script for public domains: `id.nodedc.ru`, `hub.nodedc.ru`, `ops.nodedc.ru`, `ops-agents.nodedc.ru`.
- Decide whether release tags should be coordinated across the three repos after stable production milestones.

5
infra/synology/README.md
View File

@ -7,7 +7,7 @@
- Не выполнять `docker stop`, `docker restart`, `docker compose down`, `docker system prune` для старых проектов. - Не выполнять `docker stop`, `docker restart`, `docker compose down`, `docker system prune` для старых проектов.
- Новый compose project: `nodedc-platform`. - Новый compose project: `nodedc-platform`.
- Новая папка на NAS: `/volume1/docker/nodedc-platform`. - Новая папка на NAS: `/volume1/docker/nodedc-platform`.
- Внутренний HTTP edge использует `18080`, Tasker upstream — `18090`. - Внутренний HTTP edge использует `18080`, Tasker upstream — `18090`, Ops Agents Gateway upstream — `18190`.
- Старые порты `9000` и `5678` заняты старым `nodedc-demo` и не используются. - Старые порты `9000` и `5678` заняты старым `nodedc-demo` и не используются.
## Текущие внешние домены ## Текущие внешние домены
@ -16,6 +16,7 @@
https://id.nodedc.ru -> Authentik https://id.nodedc.ru -> Authentik
https://hub.nodedc.ru -> Launcher / Hub https://hub.nodedc.ru -> Launcher / Hub
https://ops.nodedc.ru -> Tasker / Operational Core https://ops.nodedc.ru -> Tasker / Operational Core
https://ops-agents.nodedc.ru -> Ops Agents Gateway / MCP
``` ```
В `Caddyfile.http` эти домены проксируются через локальный HTTP edge, но upstream получает `X-Forwarded-Proto: https` и `X-Forwarded-Port: 443`. В `Caddyfile.http` эти домены проксируются через локальный HTTP edge, но upstream получает `X-Forwarded-Proto: https` и `X-Forwarded-Port: 443`.
@ -46,6 +47,7 @@ http://task.nas.nodedc:18090
- `deploy-current.sh` синхронизирует compose, Caddyfile, Authentik templates и опционально Launcher source в NAS mount. - `deploy-current.sh` синхронизирует compose, Caddyfile, Authentik templates и опционально Launcher source в NAS mount.
- `backup-current.sh` делает snapshot Launcher runtime/uploads/Auth templates/config и готовит команду `pg_dump` для Authentik Postgres. - `backup-current.sh` делает snapshot Launcher runtime/uploads/Auth templates/config и готовит команду `pg_dump` для Authentik Postgres.
- Tasker поднимается отдельным compose из `NODEDC_TASKMANAGER/plane-app/docker-compose.yaml` на порту `18090`. - Tasker поднимается отдельным compose из `NODEDC_TASKMANAGER/plane-app/docker-compose.yaml` на порту `18090`.
- Ops Agents Gateway поднимается отдельным compose из `NODEDC_TASKMANAGER_CODEXAPI/docker-compose.synology.yml` на `127.0.0.1:18190`; Synology reverse proxy должен вести `ops-agents.nodedc.ru` на этот порт, а не на `18090`.
## Синхронизация текущего состояния ## Синхронизация текущего состояния
@ -87,6 +89,7 @@ bash /volume1/docker/nodedc-platform/backups/platform-current-YYYYMMDD-HHMMSS/ru
- `nodedc/plane-live:local` - `nodedc/plane-live:local`
- `nodedc/plane-backend:local` - `nodedc/plane-backend:local`
- `nodedc/plane-proxy:ru` - `nodedc/plane-proxy:ru`
- Для Ops Agents Gateway отдельный registry image пока не обязателен: deploy из source repo выполняется через `docker compose --env-file .env -f docker-compose.synology.yml up -d --build`.
- Создать `.env.synology` из `.env.synology.example` и заменить все `replace-with-*`. - Создать `.env.synology` из `.env.synology.example` и заменить все `replace-with-*`.
- Создать `plane.env.synology` для Tasker из `plane.env.staging.example`, но с HTTP URL на `*.nas.nodedc:18080` и портами `18090/18490`. - Создать `plane.env.synology` для Tasker из `plane.env.staging.example`, но с HTTP URL на `*.nas.nodedc:18080` и портами `18090/18490`.