Interne Meldestelle einrichten: Schritt-für-Schritt-Anleitung mit OpenWhistle

Diese Anleitung führt Sie Schritt für Schritt durch die Installation und Erstkonfiguration von OpenWhistle. Am Ende haben Sie eine vollständig funktionsfähige, HinSchG-konforme interne Meldestelle — selbst gehostet, DSGVO-konform, kostenlos.

Voraussetzungen

• Ein Linux-Server (Ubuntu 22.04 LTS oder Debian 12 empfohlen) mit mindestens 1 GB RAM
• Eine Domain, die auf Ihren Server zeigt (z. B. meldestelle.ihr-unternehmen.de)
• Root- oder sudo-Zugriff auf den Server
• Grundlegende Terminal-Kenntnisse

Schritt 1: Server bereitstellen

Schritt 2: Docker installieren

# Docker Repository hinzufügen
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker CE installieren
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Aktuellen Benutzer zur Docker-Gruppe hinzufügen
sudo usermod -aG docker $USER
newgrp docker

# Installation prüfen
docker --version
docker compose version

Schritt 3: OpenWhistle konfigurieren

git clone https://github.com/openwhistle/OpenWhistle.git
cd OpenWhistle

# Beispiel-Konfiguration als Vorlage kopieren
cp .env.example .env

Öffnen Sie .env in einem Editor und passen Sie die wichtigsten Einstellungen an:

# Zwingend erforderlich: starker, zufälliger Schlüssel (mindestens 32 Zeichen)
# Generieren Sie einen sicheren Schlüssel mit:
# openssl rand -hex 32
SECRET_KEY=ihr-geheimer-schluessel-hier-ersetzen

# Ihre Domain
APP_BASE_URL=https://meldestelle.ihr-unternehmen.de

# Datenbankpasswort (stark wählen)
POSTGRES_PASSWORD=sicheres-passwort-hier

# Optionale E-Mail-Benachrichtigungen bei neuen Meldungen
# SMTP_HOST=smtp.ihr-mailserver.de
# SMTP_PORT=587
# SMTP_USER=compliance@ihr-unternehmen.de
# SMTP_PASS=mail-passwort
# NOTIFY_EMAIL=compliance@ihr-unternehmen.de

Schritt 4: HTTPS einrichten

# Certbot installieren
sudo apt-get install -y certbot python3-certbot-nginx

# Zertifikat ausstellen (Domain anpassen)
sudo certbot certonly --standalone \
  -d meldestelle.ihr-unternehmen.de \
  --non-interactive --agree-tos \
  -m admin@ihr-unternehmen.de

Tragen Sie die Zertifikatspfade in der .env ein:

SSL_CERT=/etc/letsencrypt/live/meldestelle.ihr-unternehmen.de/fullchain.pem
SSL_KEY=/etc/letsencrypt/live/meldestelle.ihr-unternehmen.de/privkey.pem

Schritt 5: OpenWhistle starten

# Alle Container starten (inkl. PostgreSQL, Redis, OpenWhistle, nginx)
docker compose -f docker-compose.prod.yml up -d

# Status prüfen
docker compose -f docker-compose.prod.yml ps

# Logs anzeigen (optional)
docker compose -f docker-compose.prod.yml logs -f app

Nach etwa 30 Sekunden sollte OpenWhistle unter Ihrer Domain erreichbar sein. Der Health-Check-Endpunkt gibt schnell Auskunft:

curl https://meldestelle.ihr-unternehmen.de/health
# Erwartete Antwort: {"status":"healthy","database":"ok","redis":"ok"}

Schritt 6: Admin-Account erstellen

Im Setup-Wizard:

1. Wählen Sie einen Benutzernamen und ein starkes Passwort für den Admin-Account
2. Scannen Sie den angezeigten QR-Code mit Ihrer Authenticator-App (Google Authenticator, Authy, Bitwarden, etc.)
3. Geben Sie den 6-stelligen TOTP-Code zur Bestätigung ein
4. Die Meldestelle ist jetzt betriebsbereit

Schritt 7: Grundkonfiguration im Admin-Dashboard

Melden Sie sich unter /admin/login an. Im Admin-Dashboard empfehlen wir folgende erste Schritte:

Kategorien einrichten

Unter /admin/categories richten Sie die Kategorien für Meldungen ein. Beispiele: "Finanzielle Unregelmäßigkeiten", "Sicherheitsverstöße", "Umweltverstöße", "Diskriminierung". Kategorien helfen beim Routing zu den zuständigen Personen.

Weitere Admin-Konten anlegen

Unter /admin/users legen Sie weitere Mitarbeitende an, die Meldungen bearbeiten dürfen. TOTP-Einrichtung ist für alle Konten verpflichtend.

E-Mail-Benachrichtigungen testen

Wenn Sie SMTP konfiguriert haben, senden Sie eine Test-Meldung über das Whistleblower-Formular und prüfen Sie, ob die Benachrichtigung ankommt.

Schritt 8: Meldestelle an Mitarbeiter kommunizieren

Gemäß § 13 HinSchG müssen Sie alle Beschäftigten über die Existenz und Nutzung der Meldestelle informieren. Empfohlene Maßnahmen:

• Interne E-Mail-Ankündigung mit Link zur Meldestelle und Erklärung des Schutzrahmens
• Eintrag im Intranet / Wiki
• Erwähnung im Mitarbeiterhandbuch oder Verhaltenskodex
• Optional: Poster in Gemeinschaftsbereichen (auch für Personen ohne Computer-Zugang)

Automatische Updates einrichten

Für Sicherheitsupdates empfehlen wir, regelmäßig die neueste OpenWhistle-Version einzuspielen:

# In Ihrem OpenWhistle-Verzeichnis
git pull origin main
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Oder nutzen Sie Watchtower für vollautomatische Container-Updates.

Backup-Strategie

Die wichtigsten Backup-Targets sind:

• PostgreSQL-Datenbank: tägliche pg_dump-Backups, verschlüsselt gespeichert
• .env-Datei: enthält den SECRET_KEY — ohne ihn sind alle Meldungen nicht mehr lesbar
• Anhänge: falls STORAGE_BACKEND=filesystem, das Upload-Verzeichnis sichern

# PostgreSQL-Datenbank sichern
docker exec openwhistle-db-1 pg_dump -U openwhistle openwhistle \
  | gzip > /backup/openwhistle-$(date +%Y%m%d).sql.gz

Häufige Probleme

Container startet nicht — "port is already allocated"

Port 80 oder 443 ist bereits belegt. Prüfen Sie mit sudo ss -tlnp | grep :80, welcher Prozess den Port belegt. Oft ist es Apache oder ein anderer nginx. Deaktivieren Sie diesen oder passen Sie die Port-Konfiguration in docker-compose.prod.yml an.

Datenbank-Verbindungsfehler beim Start

Die Datenbank braucht einige Sekunden zum Starten. OpenWhistle hat einen Retry-Mechanismus, aber bei sehr langsamen Systemen kann der erste Start fehlschlagen. Starten Sie den App-Container neu: docker compose -f docker-compose.prod.yml restart app.

HTTPS-Zertifikat wird nicht akzeptiert

Prüfen Sie, ob der Certbot-Zertifikatspfad korrekt in der .env eingetragen ist und ob der nginx-Container Leserechte auf das Let's Encrypt-Verzeichnis hat. Certbot-Zertifikate liegen standardmäßig in /etc/letsencrypt/live/ihr-domain/.

Weitere Ressourcen: Vollständige Dokumentation · HinSchG-Compliance-Leitfaden · GitHub Issues