Installation

Deutsch | English

Installation

HumanShield.APP wird als Docker-Compose-Stack betrieben. Alle umgebungs­spezifischen Werte kommen aus einer .env — es sind keine Werte im Code fest verdrahtet.

Voraussetzungen

• Docker Engine (aktuelle Version, ≥ 24) und Docker Compose v2 — das ist das aktuelle, in Docker integrierte docker compose-Plugin (Aufruf mit Leerzeichen). Compose v2 ist die aktuelle Generation (Versionsstände 2.x); das alte, separate docker-compose (v1, Python) ist eingestellt und wird nicht unterstützt. Prüfen mit docker compose version.
• Eine Domain oder ein vorgelagerter Reverse Proxy (optional, aber empfohlen für TLS)
• Ein SMTP-Postfach für den Mailversand (beliebiger Anbieter)

Hardware-Anforderungen

Der gesamte Stack (PostgreSQL, Redis, FastAPI-Backend, Frontend, Caddy) läuft auf einem Docker-Host. Die Werte sind Richtwerte; der Bedarf steigt mit Empfängerzahl, paralleler Nutzung und optionalen Business-Features (PDF-Reports, KI-Anbindung).

Ressource	Minimum	Empfohlen
CPU	2 vCPU	2–4 vCPU
RAM	2 GB	4 GB
Datenträger	15 GB SSD	20–40 GB SSD
Betriebssystem	Linux (x86-64 oder ARM64) mit Docker Engine (≥ 24) + Docker Compose v2 (docker compose)	dito

Einordnung der Komponenten (Anhaltswerte im Leerlauf): PostgreSQL ~150 MB, Redis ~30 MB, Backend (Python/uvicorn inkl. Add-ons) ~300 MB, Frontend ~300 MB, Caddy ~40 MB. Spitzen entstehen kurzfristig bei PDF-Erzeugung, KI-Aufrufen und großen Versand-Batches.

Hinweise:

• Minimum genügt für kleinere Organisationen (bis einige Hundert Empfänger, gelegentliche Kampagnen).
• Empfohlen gibt Reserve für größere Kampagnen, Reporting/KI und die mit jeder Kampagne wachsenden Tracking-Daten.
• Eine SSD wird für die Datenbank empfohlen (viele kleine Schreibvorgänge durch Tracking-Ereignisse).
• Netzwerk: ausgehender SMTP-Zugang (Versand) und Erreichbarkeit der APP_DOMAIN für die Zielpersonen (Tracking).
• Optionaler GeoIP-Länder-Lookup benötigt eine lokale MMDB-Datei (~10–60 MB, siehe Konfiguration).

Komponenten

Dienst	Rolle
postgres	Datenbank
redis	Cache/Queue
backend	API (FastAPI)
frontend	Dashboard (React/Vite)
caddy	Reverse Proxy / TLS

Geführte Installation (empfohlen)

Die interaktive Installationsroutine führt dich durch alle wichtigen Einstellungen, erzeugt eine gültige .env aus .env.example, generiert sichere Secrets (SECRET_KEY, DB-Passwort) und hält DATABASE_URL automatisch synchron. Sie ist zweisprachig (Deutsch/Englisch).

1. Repository klonen — holt den kompletten Stack (Code, install.sh, docker-compose.yml, .env.example) von GitHub auf den Server:

   # Falls Git noch fehlt (Debian/Ubuntu):
   sudo apt install -y git
   
   # In ein Verzeichnis deiner Wahl wechseln, z. B. /opt:
   cd /opt
   
   # Repository klonen — erzeugt den Unterordner "HumanShield.APP":
   git clone https://github.com/HumanShield-Awareness/HumanShield.APP.git
   
   # In den neuen Ordner wechseln — hier laufen alle weiteren Befehle:
   cd HumanShield.APP

   Hinweise:

   • Nach dem Klonen liegt der aktuelle Stand des main-Branch vor. Wer eine bestimmte Version betreiben möchte, checkt den zugehörigen Release-Tag aus, z. B. git checkout v0.15.0 (verfügbare Versionen: GitHub → Releases).
   • Updates später im selben Ordner mit git pull holen, danach den Stack mit docker compose up -d --build neu bauen/starten.
   • Ohne Git geht es auch: auf der GitHub-Seite über Code → Download ZIP herunterladen und entpacken. Der bequeme Update-Weg über git pull entfällt dann allerdings.

2. Routine starten:

   ./install.sh

3. Den Fragen folgen (Domain, Datenbank, Admin-Konto, SMTP, optional Lizenz). Leeres Feld = Vorgabe übernehmen.

4. Am Ende optional direkt den Stack starten lassen.

Die Routine schreibt ausschließlich in die .env (Rechte 600) — es wird nichts im Code fest verdrahtet. Eine bestehende .env kann auf Wunsch als Basis weiterverwendet werden.

Schnellstart (manuell)

1. Repository klonen (wie oben unter „Geführte Installation", Schritt 1) und .env.example nach .env kopieren.
2. .env mit echten Werten füllen (siehe unten) — niemals committen.
3. Stack starten:

   docker compose up -d

4. Datenbank-Migrationen laufen beim Start des Backends automatisch mit.
5. Dashboard über die konfigurierte Domain (bzw. https://localhost) öffnen.

Wichtige .env-Werte (generisch)

# App / Domain
APP_DOMAIN=humanshield.example.com
CADDY_SITE_ADDRESS=humanshield.example.com   # oder ":80" hinter externem TLS-Proxy

# Datenbank
POSTGRES_DB=humanshield
POSTGRES_USER=humanshield
POSTGRES_PASSWORD=change-me-strong-password

# Sicherheit
SECRET_KEY=change-me-min-32-characters-random

# Erster Admin (nur beim allerersten Start wirksam)
INITIAL_ADMIN_EMAIL=admin@example.com
INITIAL_ADMIN_PASSWORD=change-me

# SMTP (beliebiger Anbieter)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=noreply@example.com
SMTP_PASSWORD=change-me
SMTP_FROM_EMAIL=noreply@example.com
SMTP_FROM_NAME=HumanShield-Awareness
SMTP_TLS_MODE=starttls

Erster Login

Beim ersten Start wird aus INITIAL_ADMIN_EMAIL / INITIAL_ADMIN_PASSWORD ein Admin-Konto angelegt. Danach weitere Konten über Benutzer verwalten und das Start-Passwort ändern.

Add-ons & Backend-Neustart

Die kostenpflichtigen Business- und Enterprise-Add-ons werden als separate Pakete in den backend-Container eingehängt (per Volume nach /addons/…) und beim Start des Backends automatisch geladen.

⚠️ Wichtig bei Add-on-Änderungen: Das Backend läuft mit uvicorn --reload, das aber nur das App-Verzeichnis überwacht — nicht die eingehängten Add-on-Pakete. Änderungen am Code der Add-ons (neue Routen, Felder usw.) werden daher erst nach einem manuellen Neustart des Backends aktiv:

docker compose restart backend

Symptom bei vergessenem Neustart: Das Frontend ruft eine neue Add-on-Route auf, die im laufenden Prozess noch nicht existiert (HTTP 404) und zeigt eine generische Fehlermeldung. Nach dem Neustart ist die Route verfügbar.

Tracking-Erreichbarkeit

Öffnungs-/Klick-Tracking funktioniert nur, wenn Empfänger die unter APP_DOMAIN gesetzte Adresse erreichen können. Bei rein internen/VPN-Domains registrieren externe Empfänger keine Events. Viele Mail-Clients blockieren zudem das Öffnungs-Pixel — Klicks sind daher das verlässlichere Signal.

Siehe auch: Konfiguration