Add detailed explanation of multi-tenant architecture and operational guidelines in the documentation

2026-04-20 15:55:50 +02:00
parent 96f918828c
commit 31de22d460
1 changed files with 38 additions and 1 deletions
@@ -124,4 +124,41 @@ def get_items():
 **What it returns internally:**
 The `get_tenant_db` function queries `g.tenant_context` inside Flask, calculates the database name from the subdomain, and returns a live `pymongo.database.Database` object. 

-This ensures that scaling is extremely cheap on resources because 1 Application Container connects to 100 separate Tenant Databases using just 1 shared `MongoClient` pool.
+This ensures that scaling is extremely cheap on resources because 1 Application Container connects to 100 separate Tenant Databases using just 1 shared `MongoClient` pool.
+
+---
+
+
+1. Das Kernkonzept: Wie funktioniert dein Multi-Tenant-System?
+Du betreibst keinen separaten Docker-Container für jeden einzelnen Kunden (Tenant). Das wäre extrem speicherintensiv und schwer zu warten. Stattdessen nutzt du ein „Database-per-Tenant“ & „Shared-App“ Modell:
+
+Der App-Pool: In Docker laufen z.B. 3 identische app-Container, die sich die Arbeit teilen (Load-Balancing).
+Das Routing (Nginx): Ein Nutzer ruft https://schule1.deinedomain.de auf. Nginx leitet die Anfrage an irgendeinen der freien app-Container weiter.
+Die Tenant-Weiche (Python): Deine Python-App greift die Subdomain (schule1) aus der URL ab und lenkt alle Datenbankabfragen dieses Nutzers ausschließlich auf die MongoDB-Datenbank inventar_schule1.
+Das Ergebnis: 100% isolierte Daten für jeden Mandanten, aber maximale Ressourceneffizienz auf dem Server.
+2. Der Praxis-Ablauf: Einen neuen Kunden anlegen
+Um eine neue Schule oder einen neuen Kunden mit eigener Subdomain an den Start zu bringen, brauchst du nur zwei Schritte:
+
+DNS einrichten (Domain-Ebene):
+Erstelle bei deinem Domain-Provider einen A-Record oder CNAME für die Subdomain (z.B. schule1), der auf die IP deines Servers zeigt.
+
+Pro-Tipp: Richte dir einen Wildcard-Record (*.deinedomain.de) ein. Dann musst du bei neuen Kunden nie wieder in die DNS-Einstellungen gehen. Jede fiktive Subdomain zeigt dann automatisch auf deinen Server!
+Datenbank initialisieren (Server-Ebene):
+Führe deinen Wrapper auf dem Server aus, um dem Kunden eine Datenbank und einen initialen Admin-Nutzer zu generieren:
+
+Das System ist nun für diesen Kunden unter schule1.deinedomain.de voll einsatzbereit.
+
+3. Performance anpassen (Skalieren statt Neustarten)
+Wenn du plötzlich 20 neue Kunden hast und der Server langsamer wird, musst du keine neuen Instanzen für genau diese Kunden bauen. Du erhöhst einfach die allgemeine Arbeitskraft deines Docker-Compose-Netzwerks:
+
+Nginx bemerkt sofort, dass es nun 5 statt vorher z.B. 2 Container gibt, und verteilt die Last aller aktiven Subdomains dynamisch auf alle 5 Container. Es gibt dabei keine Downtime.
+
+4. Nützliche Zusatz-Infos & Pro-Tipps
+Zero-Downtime Soft-Restarts (Session Invalidation):
+Manchmal hängt ein Kunde fest oder du hast configs geändert. Anstatt den ganzen Server (und alle Kunden) neu zu starten, nutzt du .run-tenant-cmd.sh restart-tenant schule1. Das leert nur den Redis-Cache und die Sessions dieses einen Kunden. Seine Nutzer müssen sich neu einloggen, alle anderen Mandanten merken davon nichts.
+Datensicherheit / Backups:
+Da jeder Tenant eine eigene Datenbank hat (inventar_schule1, inventar_schule2), kannst du im Fall eines Datenverlusts (z.B. ein Lehrer löscht versehentlich das halbe Inventar) das Backup nur für diesen einen Kunden wiederherstellen (mongorestore --db inventar_schule1 ...), ohne die Bestandsdaten der anderen 50 Schulen zu überschreiben.
+SSL-Zertifikate:
+Damit HTTPS für alle Subdomains automatisch funktioniert, generiere beim Setup unbedingt ein Wildcard-Zertifikat via Let's Encrypt (z.B. certbot certonly --manual -d "*.deinedomain.de"). Sonst zeigt der Browser bei einem neu angelegten Tenant eine Sicherheitswarnung, bis du das Zertifikat manuell erneuerst.
+Kostenersparnis:
+Da alle Container geteilt werden, kannst du auf einem Standard 4GB RAM / 2 vCPU VPS (ca. 5-10 Euro im Monat) problemlos 10-20 verschiedene Schulen parallel hosten, was dieses Architekturmodell extrem skalierbar und günstig macht.