From 2f2ea4d483faa500a89c30172fd6dd78409a2316 Mon Sep 17 00:00:00 2001
From: OpenClaw <openclaw@example.com>
Date: Fri, 6 Mar 2026 23:35:43 +0000
Subject: [PATCH] docs: add Unraid deployment runbook for app and DB connection

---
 docs/deployment/unraid-runbook.md | 95 +++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 docs/deployment/unraid-runbook.md

diff --git a/docs/deployment/unraid-runbook.md b/docs/deployment/unraid-runbook.md
new file mode 100644
index 0000000..b7f84f4
--- /dev/null
+++ b/docs/deployment/unraid-runbook.md
@@ -0,0 +1,95 @@
+# Unraid Deployment Runbook
+
+## Ziel
+
+Dieses Dokument beschreibt den Schritt-für-Schritt Prozess zur Inbetriebnahme der `helpyourneighbour` Anwendung auf einem Unraid-Server. Es umfasst die Einrichtung von Docker-Containern, Umgebungsvariablen, DB-Verbindung und weitere relevante Konfigurationen.
+
+## Voraussetzungen
+
+- Unraid Server (Version 6.10+ empfohlen)
+- Docker-Plugin installiert
+- Zugriff auf den Unraid WebUI
+- Einrichtung eines Docker Networks (z.B. `helpyourneighbour-net`)
+
+## Schritt-für-Schritt Anleitung
+
+### 1. Datenbank-Container einrichten
+
+#### Container Name:
+`helpyourneighbour-db`
+
+#### Image:
+`postgres:15-alpine`
+
+#### Environment-Variablen:
+```env
+POSTGRES_DB=helpyourneighbour
+POSTGRES_USER=helpyourneighbour_user
+POSTGRES_PASSWORD=secure_password_here
+```
+
+#### Volumes:
+- Host Path: `/mnt/user/appdata/helpyourneighbour-db/data`
+- Container Path: `/var/lib/postgresql/data`
+
+#### Ports:
+- Host Port: `5432`
+- Container Port: `5432`
+
+### 2. Backend-Container einrichten
+
+#### Container Name:
+`helpyourneighbour-backend`
+
+#### Image:
+`openclaw/helpyourneighbour-backend:latest`
+
+#### Environment-Variablen:
+```env
+DATABASE_URL=postgresql://helpyourneighbour_user:secure_password_here@helpyourneighbour-db:5432/helpyourneighbour
+NODE_ENV=production
+PORT=3000
+```
+
+#### Volumes:
+- Host Path: `/mnt/user/appdata/helpyourneighbour-backend/logs`
+- Container Path: `/app/logs`
+
+#### Ports:
+- Host Port: `3000`
+- Container Port: `3000`
+
+#### Netzwerk:
+- Verbinde mit dem Docker Network `helpyourneighbour-net`
+
+### 3. Healthcheck und Restart Policy
+
+#### Healthcheck (Backend):
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```
+
+#### Restart Policy:
+- `unless-stopped`
+
+### 4. Secrets Handling
+
+Die folgenden Secrets sollten als Umgebungsvariablen oder in Unraid Secrets gespeichert werden:
+
+- `DATABASE_URL`
+- `DATA_ENCRYPTION_KEY` (für Verschlüsselung von Adressen/Telefonnummern)
+
+### 5. Log-Orte
+
+- Backend Logs: `/mnt/user/appdata/helpyourneighbour-backend/logs`
+- DB Logs: `/mnt/user/appdata/helpyourneighbour-db/data`
+
+## Risiken und Fehlerbilder
+
+- **Fehlende Netzwerkverbindung**: Stelle sicher, dass beide Container im gleichen Docker Network sind.
+- **Datenbank-Init fehlgeschlagen**: Überprüfe die Umgebungsvariablen und Volumes der DB.
+- **Healthcheck-Fehler**: Prüfe den Status des Backend-Containers und Logs.