Installation

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 & Docker Compose (v2)
• Eine Domain oder ein vorgelagerter Reverse Proxy (optional, aber empfohlen für TLS)
• Ein SMTP-Postfach für den Mailversand (beliebiger Anbieter)

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