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

Schnellstart

1. Repository klonen 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