nexus/DEPLOYMENT_PLAN.md

Nexus Phase 1 Deployment Plan

Generiert: 2026-06-09T02:49 CEST | Agent: architekt

Status: ✅ Bereit zum Deployment

Build-Artefakte

Komponente	Build-Methode	Status
Backend	Docker Multi-Stage (dotnet publish in Container)	✅ Dockerfile bereit
Frontend	Docker Multi-Stage (pnpm build in Container)	✅ Dockerfile bereit
Compose	compose.yaml	✅ 3 Services definiert
Env	.env	✅ Alle Secrets gesetzt

Architektur

┌──────────────────────────────────────────────────────┐
│ VPS Host (Debian 12)                                 │
│  ┌───────────────────────────────────────────────┐   │
│  │ Docker Network: nexus                         │   │
│  │  ┌─────────┐  ┌──────────┐  ┌────────────┐   │   │
│  │  │postgres │  │   api    │  │    web     │   │   │
│  │  │ :5432   │  │ :8080    │  │ :80        │   │   │
│  │  │ 17-alp. │  │ .NET 10  │  │ nginx 1.27 │   │   │
│  │  └─────────┘  └──────────┘  └─────┬──────┘   │   │
│  │                                   │           │   │
│  └───────────────────────────────────┼───────────┘   │
│                                      │               │
│                         127.0.0.1:18880              │
│                              │                       │
│  ┌───────────────────────────┼───────────────────┐   │
│  │ Host nginx reverse proxy  │                   │   │
│  │ nexus.noveria.net :443 ───┘                   │   │
│  └───────────────────────────────────────────────┘   │
│                                                      │
│  ┌───────────────────────────────────────────────┐   │
│  │ OpenClaw Gateway (Container)                  │   │
│  │ Port 18789 ← host.docker.internal             │   │
│  └───────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────┘

---

1. Deployment (vom VPS-Host ausführen)

# Ins Nexus-Verzeichnis wechseln
cd /opt/openclaw/data/openclaw/workspace/nexus

# Prüfen ob compose.yaml und .env da sind
ls -la compose.yaml .env

# Deployment starten
docker compose up -d --build

# Logs verfolgen
docker compose logs -f

Erwartet:

• 3 Container starten: postgres, api, web
• PostgreSQL wird healthy
• API migriert Datenbank und seedet Owner-Account
• Web (nginx) lauscht auf 127.0.0.1:18880

---

2. Post-Deployment-Verifikation

2.1 Health Check

curl -s https://nexus.noveria.net/health | jq

Erwartet: JSON mit status: "Healthy", DB-Check healthy, OpenClaw-Check Status.

2.2 Agent-Inventar

curl -s https://nexus.noveria.net/api/v1/agents | jq

Erwartet: Array von Agenten oder leere Liste (404/401 möglich vor Login).

2.3 SPA-Routing

curl -sI https://nexus.noveria.net/dashboard | head -20

Erwartet: HTTP 200, content-type: text/html (nginx liefert index.html für alle Routes).

2.4 API-Dokumentation

curl -sI https://nexus.noveria.net/swagger/index.html

2.5 Container-Status

docker compose ps

Erwartet: Alle 3 Services Up (healthy).

---

3. Gateway-Neustart

Nach erfolgreichem Deployment muss der OpenClaw-Gateway neu gestartet werden, damit der Researcher-Agent aktiv wird.

⚠️ Kein docker restart möglich — kein Docker-Socket im Gateway-Container.

Im Gateway-Container (über OpenClaw-Session):

PID=$(pgrep -f "node dist/index.js gateway" | head -1)
kill -HUP $PID

Der Gateway-Container hat restart: unless-stopped in seiner eigenen Compose-Konfiguration. Ein kill (SIGTERM) auf den Node-Prozess führt automatisch zum Container-Neustart via Docker. Für graceful reload ist kill -HUP bevorzugt.

---

4. Troubleshooting

API startet nicht

docker compose logs api

Häufige Ursachen:

• PostgreSQL nicht healthy → docker compose logs postgres
• JWT_KEY / DB-Passwort falsch

Web nicht erreichbar

# Prüfen ob nginx im Container läuft
docker compose exec web nginx -t
# Prüfen ob Port gebunden ist
ss -tlnp | grep 18880

Host nginx Reverse Proxy

Falls nexus.noveria.net nicht erreichbar:

• Host nginx Config prüfen: Proxy-Pass auf http://127.0.0.1:18880
• TLS-Zertifikat gültig?

---

Abhängigkeiten

Was	Status
compose.yaml	✅ Vorhanden
.env mit Secrets	✅ Vorhanden
backend/Dockerfile	✅ Multi-Stage .NET 10
frontend/Dockerfile	✅ Multi-Stage Node 24 + nginx
frontend/nginx.conf	✅ CSP, Proxy, SPA-Routing
Host nginx Reverse Proxy	⚠️ Muss auf Port 18880 zeigen
Docker installiert auf VPS	⚠️ Vorausgesetzt