Frage aus dem Betrieb: laesst sich ein Compose-Abschnitt ueber eine Variable
in der .env zu- und abschalten, statt ihn auszukommentieren? Bedingte Bloecke
kennt Compose nicht - aber COMPOSE_PROFILES darf in der .env stehen und
aktiviert das Profil, ohne dass ein Flag noetig ist.
COMPOSE_PROFILES= -> Caddy wird nicht angelegt (Standard)
COMPOSE_PROFILES=caddy -> Caddy startet bei `docker-compose up -d` mit
Vorteil gegenueber `--profile caddy`: der Schalter wirkt auch bei down, logs
und ps, wo das Flag leicht vergessen wird und dann verwaiste Container
zurueckbleiben.
Empirisch geprueft mit einem separaten Testprojekt (compose 1.29.2): ohne den
Eintrag startete nur der ungeschuetzte Dienst, mit Eintrag beide.
Dokumentiert in .env.example, im Kommentar am caddy-Dienst und in der README.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Der zweite Stack unter docker/ war ein Duplikat aus Februar, das nie
mitgepflegt wurde - und genau deshalb schwer zu finden und leicht falsch zu
bedienen. Statt ihn zu loeschen (Caddy ist fuer Betreiber ohne eigenen
Reverse-Proxy zurecht gewuenscht) ist er jetzt in den Hauptstack integriert:
- caddy als optionaler Dienst mit `profiles: ["caddy"]` in docker-compose.yml.
Ohne `--profile caddy` wird er nicht einmal angelegt - empirisch geprueft mit
einem separaten Testprojekt: `up -d` startete nur den ungeschuetzten Dienst.
Der laufende Stack bleibt damit unveraendert.
- Caddyfile in den Projektstamm verschoben, proxy-Ziel auf den Dienstnamen
`opencrm` angepasst, Zertifikate unter ./data/caddy wie alle anderen Daten.
- DOMAIN, CADDY_DIR und CADDY_CONFIG_DIR in die .env.example aufgenommen.
- docker/ entfernt (Dockerfile, entrypoint.sh, docker-compose.yml,
.env.example, README.md). Das dortige Dockerfile basierte noch auf Alpine -
genau die Variante, von der das Projekt wegen Prisma-/TLS-Problemen bewusst
auf node:20-slim gewechselt ist. Das gepflegte backend/Dockerfile baut
Frontend und Backend ebenso.
- README: Abschnitt "Docker (Produktion)" ersetzt durch "Betrieb mit eigenem
SSL", inkl. Hinweisen zu Let's-Encrypt-Limits, DNS-Voraussetzung,
HTTPS_ENABLED und dem weiterhin offenen App-Port. Projektbaum und
.dockerignore nachgezogen.
Geprueft: docker-compose config gueltig, caddy validate gueltig, laufende
Container unberuehrt.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Der Stack bleibt bewusst erhalten: Er richtet sich an Betreiber OHNE eigenen
Reverse-Proxy, weil Caddy das Zertifikat selbst holt und erneuert. Er war
allerdings seit Februar stehengeblieben und reichte zehn Variablen nicht an
den Container durch - teils sicherheitsrelevant.
Behoben:
- HTTPS_ENABLED ergaenzt (Default true, Caddy terminiert TLS). Fehlte bisher
komplett, dadurch waere der Refresh-Cookie OHNE Secure-Attribut gesetzt
worden und trust proxy falsch gewesen.
- JWT_EXPIRES_IN Default von 7d auf 15m korrigiert - der Wert galt dem
ACCESS-Token und stammte aus der Zeit vor dem Access-/Refresh-Pattern. Ein
Access-Token mit einer Woche Lebensdauer im Browser-Speicher macht das
XSS-Fenster unnoetig gross.
- JWT_REFRESH_EXPIRES_IN, CORS_ORIGINS, LISTEN_ADDR, SSRF_BLOCK_PRIVATE_IPS
ergaenzt. JWT_REFRESH_EXPIRES_IN stand bereits in docker/.env.example,
wurde aber nie durchgereicht - dieselbe Fehlerklasse wie beim Audit-Siegel.
- Caddyfile: gzip fuer /api/* deaktiviert (BREACH, CVE-2013-3587). Die
Konfiguration komprimierte bisher alles, obwohl die README das fuer die
API ausdruecklich ausschliesst. Statische Assets bleiben komprimiert.
Mit `caddy validate` geprueft.
- docker/.env.example um die neuen Variablen erweitert, dazu ein Hinweis auf
Sonderzeichen im DB-Passwort (dieser Stack setzt die DATABASE_URL direkt
zusammen, anders als der Entrypoint im Projektstamm).
- README benennt jetzt, wann welcher Stack der richtige ist.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ohne diesen Fix waere das Siegel im Docker-Betrieb wirkungslos geblieben - die
Variable wurde nirgends an den Container durchgereicht. docker-compose.yml
listet die Umgebungsvariablen einzeln auf und speist sie aus der .env im
Projektstamm; ein env_file gibt es nicht, backend/.env wird vom Container also
gar nicht gelesen. Dokumentiert und ergaenzt hatte ich bisher nur
backend/.env.example - also die Datei, die fuer den Container irrelevant ist.
- AUDIT_HMAC_KEY und AUDIT_HMAC_KEY_OLD in docker-compose.yml und in
docker/docker-compose.yml aufgenommen (beide mit :- Default, damit ohne Wert
weiterhin fail-safe ungesiegelt geschrieben wird)
- beide Variablen samt Erklaerung in die .env.example im Projektstamm und in
docker/.env.example uebernommen
- README benennt jetzt explizit, welche Datei fuer welchen Betrieb gilt
(Stamm-.env bei Docker, backend/.env nur ohne Container)
Verifiziert: `docker-compose config` loest AUDIT_HMAC_KEY korrekt auf.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
.env.example zeigt jetzt wie bei den anderen Secrets einen sichtbaren
Platzhalter an der Variablen statt eines leeren Werts - verstaendlicher, aber
mit Schutz dagegen: ein nicht ersetzter Platzhalter (enthaelt < oder >, oder
beginnt mit change/dein/your/hier) gilt NICHT als Schluessel. Sonst wuerde mit
einem oeffentlich im Repository stehenden Wert gesiegelt, was Sicherheit
vortaeuscht. Das Backend warnt in dem Fall im Log und laesst das Siegel aus.
Verifiziert: mit Platzhalter geschriebene Zeile bleibt hashVersion 2.
Dabei aufgefallen und dokumentiert: Wird das Siegel nach Aktivierung wieder
abgeschaltet (Schluessel fehlt, z. B. beim Rebuild verloren), sind die in
dieser Zeit entstandenen Eintraege ungesiegelt und werden beanstandet, sobald
der Schluessel zurueck ist. Das ist Absicht - ein ungesiegelter Eintrag
inmitten gesiegelter ist von einer Faelschung nicht zu unterscheiden. Warnung
in README und .env.example.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Frage aus dem Betrieb: bestehende Installation hat noch keinen
AUDIT_HMAC_KEY - was passiert beim nachtraeglichen Setzen? Antwort jetzt in
README und .env.example: setzen, neu starten, fertig. Bestehende Eintraege
bleiben unveraendert gueltig, neue werden gesiegelt, alt und neu koexistieren
ohne Fehlalarm. Nachgemessen auf gemischtem Bestand (4903 x V1, 57 x V2,
67 x V3): 0 Beanstandungen. Rueckwirkend siegeln ist nicht moeglich.
Dabei zwei Fehler in der eigenen Doku gefunden und korrigiert:
1. Behauptet war, nach dem Leeren von AUDIT_HMAC_KEY_OLD seien alte Eintraege
"nicht mehr pruefbar". Tatsaechlich werden sie als MANIPULIERT gemeldet -
ein falscher Schluessel ist von einer Faelschung nicht zu unterscheiden.
Gemessen: 67 Eintraege als manipuliert. Nur wenn GAR KEIN Schluessel
gesetzt ist, gilt "nicht pruefbar". Doku entsprechend korrigiert, inkl.
Warnung, das Feld nicht voreilig zu leeren.
2. AUDIT_HMAC_KEY_OLD bot nur einen Platz. Beim ZWEITEN Wechsel waeren alle
mit dem ersten Schluessel gesiegelten Eintraege faelschlich als
manipuliert erschienen (reproduziert: 67). Das Feld nimmt jetzt eine
kommagetrennte Liste entgegen; verifiziert: mit beiden Alt-Schluesseln
0 Beanstandungen, mit nur dem juengsten 67.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
README und .env.example erklaeren jetzt zuerst in Alltagssprache, was das
Audit-Log ist, wogegen der Schluessel schuetzt und was passiert, wenn man ihn
weglaesst oder verliert - inklusive Bild vom Notarstempel. Die technische
Ebene bleibt vollstaendig erhalten, in der README als aufklappbarer Block
(Hash-Versionen 1/2/3, Version-Floor, Loeschungs-Manifest, Rueckgabefelder von
/verify, bekannte Grenze) und in .env.example als eigener Abschnitt.
Ausserdem dokumentiert: Schluesselwechsel ueber AUDIT_HMAC_KEY_OLD ohne
Rehash, pro Umgebung ein eigener Schluessel, und die Warnung zu den beiden
Endpunkten mit Nebenwirkung (rehash/cleanup).
AUDIT_HMAC_KEY zusaetzlich in die Production-Checkliste aufgenommen.
Korrigiert: Die Integritaetspruefung ist NICHT ueber die Oberflaeche
erreichbar (verifyIntegrity wird von keiner Komponente genutzt) - die Doku
zeigt jetzt den API-Aufruf. Rechte, Endpunkte und Rueckgabefelder gegen den
Code geprueft.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Eigene Unterrubrik unter "Erster Login": wie man auf bestehender DB
(z.B. Staging nach Reset) datenerhaltend bekannte Zugangsdaten herstellt.
Betont, dass der Seed nur Rollen + Admin-User upsertet (keine Kundendaten),
das SEED_ADMIN_PASSWORD>=25-Zeichen-Verfahren + RUN_SEED, und dass
Portal-Passwoerter danach im UI gesetzt werden.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
SIM-cardUser, EmailProvider-Label-Override etc.)
todo.md: rund 14 neue Erledigt-Einträge seit dem letzten Stand –
gruppiert nach Feature (Folgezähler-Workflow, Anzeige-/UX-Polishing,
Pentest 42.5/43.5/43.6) und im klassischen "kompakter Header +
Bullets"-Stil.
README.md:
- Zähler-Bullet um Lieferadress-Pflicht + Folgezähler-Kette ergänzt
- Strom/Gas-Vertragsfelder um Verbrauchs-Schätzwert aus Vorvertrag,
HT/NT, Sofort-/Neukunden-Bonus, Folgezähler-Wechseldatum + Endstand
- SIM-Karten-Liste um "Kartennutzer" für Firmen-/Familienverträge
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Die README versprach weiterhin "admin@admin.com / admin" als Default,
aber Pentest Runde 12 hat das hardcoded "admin" entfernt
(Komplexitäts-Policy-Verletzung). Der Seed generiert jetzt ein
28-Zeichen-Zufallspasswort und schreibt es einmal nach stdout.
Aktualisiert:
- Quick-Start-Header: Hinweis statt direktes Passwort
- "Erste Inbetriebnahme"-Block: docker-logs-Befehl + SEED_ADMIN_PASSWORD-Alternative
- "Erster Login"-Sektion: vollständige Anleitung inkl. Beispiel-Ausgabe
- "Production-Deployment"-Checkliste: aktualisiert
- .env.example: SEED_ADMIN_PASSWORD-Block dokumentiert
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Neue Section "Deployment-Modus: On-Prem vs. Cloud" im Production-
Deployment-Block. Erklaert, warum On-Prem-Default private IPs
erlaubt (Plesk/Dovecot lokal) und wann der Flag fuer Cloud-Deploys
auf true gesetzt werden soll. Cloud-Metadata-Endpoints sind
unabhaengig vom Flag immer geblockt.
.env.example: SSRF_BLOCK_PRIVATE_IPS=false als Default mit Block-
Kommentar.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Folge zur User-Frage: Snippet auch für / anwenden. Wichtiger Punkt
dokumentiert: NPM-Custom-Location mit prefix-`/` würde ALLE Pfade
außer /api/* fangen (auch /assets/*.js) → JS-Bundle unkomprimiert
~500 KB statt 150 KB. Stattdessen exact-match `location = /` nutzen,
das fängt nur die Root-URL ohne weitere Pfad-Komponente.
Zwei Varianten dokumentiert:
- Variante A: Custom Location im NPM-UI mit „= /" (falls Feld das
akzeptiert)
- Variante B: server-level snippet im Advanced-Tab des Proxy-Hosts
Plus Verifikations-Befehle für „/" ohne gzip + „/assets/*.js" weiter
mit gzip.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pentest-Tools (testssl) melden BREACH weiter für die Root-URL, weil
die SPA-index.html bewusst weiter gzip-komprimiert ausgeliefert wird
(Performance: 50 KB → ~10 KB). Das ist nicht ausnutzbar, weil keine
Secrets/Reflektionen im HTML-Body sind. README erklärt jetzt explizit
warum + wie man es trotzdem loswerden kann (zusätzliche NPM-Custom-
Location für /, Trade-off: 40 KB extra pro Tab-Reload).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
SECURITY-HARDENING.md:
- Runde 11 "Externer Pentest-Folge: Header-Hygiene + Klartext-Audit":
HSTS-Doppel-Header weg, Cache-Control je nach Pfad differenziert,
CSP No-Fallback-Direktiven + frame-ancestors auf 'self', BREACH-
Mitigation via gzip off im Reverse-Proxy für /api/*, Server-/
X-Served-By-Banner entfernt, Audit-Log für die 6 Klartext-Passwort-
Read-Endpoints (CRITICAL).
- Runde 12 "JWT raus aus localStorage": Branchenstandard-Refresh-Cookie-
Pattern für die SPA. Access-Token (15 min) nur in JS-Memory,
Refresh-Token (7d) im httpOnly-Cookie. Auth-Middleware verweigert
Refresh-Tokens als Bearer (type-Claim). Axios-Interceptor mit
Single-Flight-Refresh-Retry. Tabelle der Live-Tests.
README.md:
- Tech-Stack-Auth-Zeile beschreibt jetzt die Access/Refresh-Architektur
- .env-Beispiel: JWT_EXPIRES_IN=15m + neue JWT_REFRESH_EXPIRES_IN=7d
- Production-Deployment-Hinweis: Frontend und API müssen über dieselbe
Origin laufen (SameSite=Strict-Cookie), sonst funktioniert /auth/refresh
cross-site nicht und User wird alle 15 min ausgeloggt
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Im selben /api/-Custom-Location-Block des BREACH-Fixes auch gleich die
Server-Banner-Hygiene ergänzt: `more_clear_headers Server X-Served-By;`
über das headers-more-Modul (bei NPM standardmäßig dabei) entfernt die
Information-Disclosure-Header, die Pentest-Tools wie Nikto sonst als
low-Finding flaggen.
Plus zusätzlicher Verifikations-curl, der prüft dass beide Header weg
sind.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pentest mit testssl markiert die Prod-Instanz wegen aktivierter gzip-
Komprimierung als BREACH-anfällig (CVE-2013-3587, "Ausnutzbar: Ja").
Die JWT-SPA-Architektur hält das Risiko praktisch klein, der Audit-
Marker bleibt aber medium.
README-Sektion „Production-Deployment" um expliziten Hinweis ergänzt:
gzip nur für statische Assets erlauben, für /api/* deaktivieren. Mit
Setup-Schritten für Nginx Proxy Manager (Custom Locations) und Plain
Nginx + Verifikationsbefehl.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Schließt die Lücke „nach Import landet die ZIP nicht im Image-Default":
./factory-import.sh --save-as-builtin
→ entpackt die ZIP nach erfolgreichem DB-Import zusätzlich in
backend/factory-defaults/ (alter Inhalt vorher aufgeräumt, README.md
und .gitkeep bleiben). Beim nächsten Image-Build sind die Defaults
drin und seeden frische VMs automatisch.
README-Abschnitt „Factory-Defaults" komplett überarbeitet:
- Drei Transport-Pfade explizit erklärt (laufende DB / Drop-Box / Image)
- HTML-Standardtexte + AppSetting-Whitelist dokumentiert
- Auto-Seed-Verhalten + Berechtigungen aktualisiert
- Typische Workflows als End-zu-End-Sequenz inkl. scp-Sync
Live verifiziert: STALE_FILE.txt im backend/factory-defaults/ wurde beim
--save-as-builtin sauber entfernt, README.md blieb erhalten, Subfolder neu
befüllt.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Big Move: vom backend-only-Setup zum vollständigen Container-Stack.
📁 Neue Struktur
- /.env (lokal, nicht getrackt) – zentrale Konfiguration für Dev + Docker
- /.env.example – Template mit allen Variablen
- /data/{db,uploads,factory-defaults,backups}/ – Bind-Mounts statt Volumes
(auf Wunsch: Daten bleiben im Projektverzeichnis)
- /backend/Dockerfile – Multi-Stage Build (Frontend + Backend)
- /backend/docker-entrypoint.sh – wartet auf DB, prisma db push, optional seed
🐳 docker-compose.yml (neu konsolidiert)
- mariadb 10.11 mit Bind-Mount ./data/db
- opencrm-app (Backend serviert Frontend statisch in production)
- adminer mit Theme pepa-linha-dark als DB-UI
- Ports + Pfade + Secrets alle aus .env
🔧 Backend
- index.ts dotenv-Loader: lädt zuerst Root /.env, dann backend/.env als
Fallback. Funktioniert nahtlos für npm run dev und für Container.
- backend/.env.example als Legacy-Fallback dokumentiert
📝 README
- Quick-Start mit Docker als empfohlener Default (3 Befehle)
- Tabelle der Daten-Verzeichnisse
- Hinweis auf RUN_SEED=true beim ersten Start
⚙ Konfigurierbar via .env
- OPENCRM_PORT (Backend extern), ADMINER_PORT (DB-UI), DB_PORT
- Daten-Pfade (DATA_DIR, DB_DATA_DIR, UPLOADS_DIR etc.)
- DB_NAME/USER/PASSWORD, JWT_SECRET, ENCRYPTION_KEY
- ADMINER_DESIGN (Theme-Auswahl)
Hinweis: Vor dem ersten `docker compose up -d` muss das laufende
`npm run dev`-Backend gestoppt werden (Port + DB-Conflict). Das alte
Volume `opencrm_mariadb_data` bleibt unangetastet als Notfall-Backup.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
-ip-address 0.0.0.0 bei plesk bin secret_key --create funktioniert NICHT,
um alle IPs zu erlauben. Stattdessen muss der Parameter komplett weggelassen
werden. Warnhinweis in der README ergänzt.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Neuer Abschnitt erklärt Schritt-für-Schritt wie man den API-Key in Plesk anlegt:
- Variante 1: Über die Plesk-Oberfläche (Mein Profil → API-Token)
- Variante 2: Über SSH (plesk bin secret_key --create)
- Hinweise zur REST-API-Extension (falls API-Key-Button fehlt)
- Firewall-Konfiguration für Port 8443
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Haupt-README.md: neuer Abschnitt mit Abgrenzung zu Datenbank-Backup, Schritt-
für-Schritt-Anleitung für Export und Import, Idempotenz-Hinweis, Berechtigungen.
backend/factory-defaults/README.md: ausführliche Referenz mit Struktur-Beispielen
aller JSON-Dateien (Provider, CancellationPeriod, ContractDuration,
ContractCategory, PdfTemplate), Teil-Import-Anleitung, Merge-Beispiele.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
duffyduckandClaude Opus 5
Stefan Hacker