# Synology deploy checklist

This service is the NODE.DC Operational Agents Gateway for Tasker/Operational Core MCP traffic.

## Network model

- Public URL: `https://ops-agents.nodedc.ru`.
- Synology reverse proxy: `HTTPS 443` → `HTTP 127.0.0.1:18190`.
- Container app port stays `4100`.
- Docker host port is controlled by `HOST_PORT=18190`.
- Do not use `18090` for this module: that host port is reserved by Tasker / Operational Core.
- No router changes are required if `443` already reaches Synology and Synology owns the reverse proxy rule.

## Required env

Create `.env` from `.env.synology.example` and replace every `replace-with-*` value:

```env
NODE_ENV=production
HOST=0.0.0.0
PORT=4100
HOST_PORT=18190
LOG_LEVEL=info

NODEDC_AGENT_GATEWAY_PUBLIC_URL=https://ops-agents.nodedc.ru
NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN=<strong-random-secret>
NODEDC_LAUNCHER_INTERNAL_URL=<launcher-url-reachable-from-synology>
NODEDC_TASKER_INTERNAL_URL=<tasker-url-reachable-from-synology>
NODEDC_INTERNAL_ACCESS_TOKEN=<tasker-internal-access-token>

POSTGRES_DB=nodedc_agent_gateway
POSTGRES_USER=nodedc_agent_gateway
POSTGRES_PASSWORD=<strong-random-postgres-password>
```

`NODEDC_TASKER_INTERNAL_URL` and `NODEDC_LAUNCHER_INTERNAL_URL` must be reachable from the Synology host/container. If Tasker and Launcher are still local-only on a workstation, deploy the gateway next to them or expose a private internal route first.

## Backup before deploy

Create a timestamped backup directory on the Synology host:

```bash
export BACKUP_DIR="$HOME/nodedc-backups/ops-agents-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
```

Backup current compose/env files if the service already exists:

```bash
cp -a docker-compose.synology.yml .env "$BACKUP_DIR"/ 2>/dev/null || true
docker compose --env-file .env -f docker-compose.synology.yml ps > "$BACKUP_DIR/compose-ps.txt" 2>/dev/null || true
```

Backup database if Postgres is already running:

```bash
docker compose --env-file .env -f docker-compose.synology.yml exec -T postgres \
  pg_dump -U "${POSTGRES_USER:-nodedc_agent_gateway}" "${POSTGRES_DB:-nodedc_agent_gateway}" \
  > "$BACKUP_DIR/postgres.sql"
```

## Deploy

```bash
docker compose --env-file .env -f docker-compose.synology.yml pull
docker compose --env-file .env -f docker-compose.synology.yml up -d --build
```

If the repository is deployed from source and not from a registry image, `up -d --build` is enough. The production compose does not publish Postgres and binds the gateway to `127.0.0.1:18190`; DSM reverse proxy should target that local address.

## Verification

Local host checks:

```bash
curl -fsS http://127.0.0.1:18190/healthz
curl -fsS http://127.0.0.1:18190/readyz
curl -fsS -i http://127.0.0.1:18190/mcp | head
```

Public checks after DNS/reverse proxy:

```bash
curl -fsS https://ops-agents.nodedc.ru/healthz
curl -fsS https://ops-agents.nodedc.ru/readyz
curl -fsS -i https://ops-agents.nodedc.ru/mcp | head
```

Expected behavior:

- `/` returns the public NODE.DC Operational Agents Gateway page.
- `GET /mcp` returns a browser-safe informational page with HTTP `405`.
- `POST /mcp` is the real MCP JSON-RPC endpoint and requires `Authorization: Bearer <agent-token>`.
- `/readyz` does not expose internal Launcher/Tasker URLs or token configuration.

## Tasker integration

Tasker must call the gateway by internal URL:

```env
PLANE_NODEDC_AGENT_GATEWAY_URL=http://<synology-or-gateway-host>:18190
PLANE_NODEDC_AGENT_GATEWAY_TOKEN=<same value as NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN>
```

After changing Tasker backend env, rebuild/restart the Tasker backend runtime so workspace settings can create agents and tokens through the gateway.