# 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)

```bash
# 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
```bash
curl -s https://nexus.noveria.net/health | jq
```
Erwartet: JSON mit `status: "Healthy"`, DB-Check `healthy`, OpenClaw-Check Status.

### 2.2 Agent-Inventar
```bash
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
```bash
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
```bash
curl -sI https://nexus.noveria.net/swagger/index.html
```

### 2.5 Container-Status
```bash
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):**
```bash
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
```bash
docker compose logs api
```
Häufige Ursachen:
- PostgreSQL nicht healthy → `docker compose logs postgres`
- JWT_KEY / DB-Passwort falsch

### Web nicht erreichbar
```bash
# 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 |