# Registry and Coordinator deployment (Phases 10, 10.1, 11, 12, TLS Gate) How the Registry and the Coordinator run on `coa-infra-01`, how to rebuild or restart them, and what the gates checked. Protocols: [REGISTRY_PROTOCOL.md](REGISTRY_PROTOCOL.md), [CONTROL_PROTOCOL.md](CONTROL_PROTOCOL.md). Node facts: [INFRASTRUCTURE.md](INFRASTRUCTURE.md), [VPS_BASELINE.md](VPS_BASELINE.md). `` is the node's public IPv4 (kept out of git); no secret is in this file. Production hostname: `coa-manager.duckdns.org`. ## Topology ``` Internet | 22/tcp (sshd) 80/tcp (redirect to 443), 443/tcp (Caddy), 40000-43999/tcp (Game Relay dynamic pool) v Caddy :443 /registry/* -> coa-registry:8080 network coa-ingress (HTTPS; ACME Let's Encrypt) :443 /coord/* -> coa-coordinator:8081 network coa-ingress (WSS WebSocket; Phase 12) :443 /relay/v1/* -> coa-relay:8082 network coa-ingress (Host WSS control session) | Registry / Coordinator / Relay +--- network coa-db (internal) ---+ v PostgreSQL container (alias coa-postgres:5432) ``` * Registry and PostgreSQL publish **no host port**. `docker ps` shows `8080/tcp` and `5432/tcp` (exposed inside Docker networks only). * Public listening surface of the host (`ss -tulnH`) is strictly limited to `22/tcp` (SSH), `80/tcp` (HTTP redirect), `443/tcp` (Caddy HTTPS / WSS), and `40000-43999/tcp` (Game Relay TCP game traffic pool). Never add `5432:5432` or `8080:8080`. * The Registry joins `coa-ingress` (to be reached by Caddy) and `coa-db` (to reach PostgreSQL). PostgreSQL joins only `coa-db`, which is `--internal`. * The Game Relay container (`coa-relay`) handles the host-networked port pool `40000-43999/tcp` for direct client Auth/World byte forwarding, with its control WebSocket bridged via Caddy at `/relay/v1/host`. * Caddy serves public HTTPS and WSS on `coa-manager.duckdns.org` with automatic Let's Encrypt ACME certificate management. Port 80 automatically redirects (308 Permanent Redirect) to HTTPS. Certificate state and ACME account metadata are stored in persistent Docker volumes `coa-caddy_caddy_data` and `coa-caddy_caddy_config`. ## Files (in git: `services/coa-registry/deploy/`) | In git | On the node | |---|---| | `postgres.compose.yaml` | `/opt/coa/postgres/compose.yaml` | | `registry.compose.yaml` | `/opt/coa/registry/compose.yaml` (+ `.env`: `REGISTRY_TAG`, rate limits) | | `Caddyfile` | `/opt/coa/caddy/Caddyfile` (the Phase -1 file is kept as `Caddyfile.phase-1.bak`, the Phase-11 one as `.phase-12.bak`) | | `../../coa-coordinator/deploy/coordinator.compose.yaml` | `/opt/coa/coordinator/compose.yaml` (+ `.env`: `COORDINATOR_TAG`) | | `../../coa-coordinator/deploy/provision-db.sh` | creates `coa_coordinator`, a role that may read four columns of `realms` (`realm_id`, `public_key`, `published`, `advert_version`) and nothing else; also creates its password file | | `../../coa-coordinator/deploy/deploy.sh` | builds the Coordinator image on the node and starts it | | `../../coa-coordinator/Dockerfile` | same shape as the Registry's (non-root uid 10002, read-only root, all capabilities dropped, no-new-privileges, 256 MB, 128 pids) | | `provision-db.sh` | run once (idempotent) as root: creates the least-privilege role `coa_registry` and database `coa_registry` | | `deploy.sh` | builds the image on the node from the working tree and restarts the stack | | `audit-db.sql` / `audit-db.sh` | what the database holds (gate item 17) | | `gate-restarts.sh` | gate items 2 and 14 | | `../Dockerfile` | multi-stage build (`rust:1-bookworm` → `debian:bookworm-slim`, non-root uid 10001, read-only root, all capabilities dropped, no-new-privileges, 256 MB, 128 pids) | ## Secrets (never in git) ``` /opt/coa/secrets/postgres_password root:root 0600 superuser of PostgreSQL; read only by the PostgreSQL entrypoint /opt/coa/secrets/registry_db_password root:10001 0440 password of the role coa_registry; mounted at /run/secrets in the Registry container /opt/coa/secrets/coordinator_db_password root:10002 0440 password of the role coa_coordinator (read-only, four columns); mounted in the Coordinator container ``` Both were generated on the node (`/dev/urandom`, 40 characters) and never displayed. The Registry connects as `coa_registry` (not a superuser, no CREATEDB/CREATEROLE, connection limit 20, owner of its own database only); PUBLIC has no access to that database. Passwords reach `psql` through the container's own secret or stdin, never a command line. Rotating: write a new value to the file, `sudo sh provision-db.sh` (it `ALTER`s the role), `docker compose up -d --force-recreate` in `/opt/coa/registry`. ## First deployment (what was done) ```bash # 1. secrets (on the node) sudo sh -c 'umask 077; head -c 48 /dev/urandom | base64 | tr -dc A-Za-z0-9 | head -c 40 > /opt/coa/secrets/postgres_password' sudo sh -c 'umask 077; head -c 48 /dev/urandom | base64 | tr -dc A-Za-z0-9 | head -c 40 > /opt/coa/secrets/registry_db_password' sudo chown root:10001 /opt/coa/secrets/registry_db_password && sudo chmod 440 /opt/coa/secrets/registry_db_password # 2. PostgreSQL (started now, for the Registry only) and the Registry's role/database cd /opt/coa/postgres && sudo docker compose up -d && sudo sh provision-db.sh # 3. from a workstation, at the repository root: build on the node and start the Registry VPS=ubuntu@ TAG=p10 sh services/coa-registry/deploy/deploy.sh # 4. Caddy: copy the Caddyfile, validate, restart sudo docker compose -f /opt/coa/caddy/compose.yaml exec caddy caddy validate --config /etc/caddy/Caddyfile sudo docker compose -f /opt/coa/caddy/compose.yaml restart caddy ``` Migrations run at start-up under an advisory lock; the Registry waits for a database that is still starting and refuses one that is ahead of its binary. Staging note: the gate ran with `REGISTRY_REGISTER_BURST=100`; the production defaults (burst 10, 10 per hour) are what `registry.compose.yaml` uses when `.env` does not override them. ## Operating ```bash cd /opt/coa/registry && sudo docker compose ps && sudo docker compose logs --tail 50 # JSON lines curl -s https://coa-manager.duckdns.org/registry/v2/healthz # {"status":"ok","protocol_version":2} curl -s https://coa-manager.duckdns.org/coord/v1/health # {"hosts":N,"protocol_version":1,"status":"ok"} sudo sh /opt/coa/registry/src/services/coa-registry/deploy/audit-db.sh # contents audit ``` Logs are structured JSON: `realm`, `endpoint`, `status`, `error` (code), `latency_ms`, and the first 8 characters of the capabilities hash. They never contain keys, signatures, headers, request bodies or the database credentials (checked: 0 occurrences of either password in any container's log). Backups: automated via `backup-db.sh` into `/opt/coa/backups` with SHA-256 verification and atomic markers (verified in Gate 15.5; see INFRASTRUCTURE.md); the data is discovery metadata that every Host re-announces by itself within a heartbeat or two. ## The Phase-10 gate Run on 2026-10-07 against `http://` (Windows workstation → Internet → Caddy → Registry → PostgreSQL). Tools: `services/coa-registry-e2e/tests/live_vps.rs` (`REGISTRY_URL=http:// cargo test --test live_vps -- --ignored --nocapture`), `deploy/gate-restarts.sh`, `deploy/audit-db.sh`, a TCP connect scan of 1–65535, and the real Manager window. | # | Item | Result | |---|---|---| | 1 | Fresh realm generates identity and registers | pass (`RegistryHost` made the UUIDv7 and the key, registered; the record shows `published`, `online`, revision 1) | | 2 | Registry restart keeps the realm | pass (`docker restart`; the realm is still registered and heartbeats with its own key) | | 3 | Host Manager restart keeps RealmId and key | pass (same id and public key, registered again as itself, revision unchanged) | | 4 | Valid heartbeat updates last_seen | pass | | 5 | Missing heartbeats → offline after the TTL, not deleted | pass (125 s without a heartbeat: `online=false`, `published=true`; a heartbeat brings it back) | | 6 | Metadata/capability change updates the record | pass (cap 60 → 70: revision 1 → 2, new capabilities stored) | | 7 | Same RealmId, another key | pass (`register` 403 `realm_key_mismatch`; heartbeat/unpublish/read 401 `invalid_signature`; the record is untouched) | | 8 | Tampered body | pass (401 `invalid_signature`) | | 9 | Old/future timestamp | pass (±1 h: 401 `bad_timestamp`; a non-increasing one: 401 `timestamp_not_monotonic`) | | 10 | Unsupported protocol version | pass (header and body: 400 `unsupported_protocol_version`) | | 11 | Oversized/hostile metadata | pass (413; 500-character name, 5000-byte description, `