WJ-Kreis-Digital-Standard

Rollout-Runbook: Ein neuer Kreis in einem Tag

Dieses Kapitel beschreibt, wie ein WJ-Kreis den Digital-Standard bei sich einführt, ohne vorher Server kaufen, Vereinsbeschlüsse fassen oder Vertrauen auf Zuruf aufbringen zu müssen. Der Weg dahin ist das Demo-first-Pattern: Ein Paten-Kreis, der den Standard bereits betreibt, hostet auf seinem Server eine vollwertige Demo-Instanz für den Interessenten-Kreis. Der testet mit echtem Look-and-Feel, aber mit Testdaten. Überzeugt die Demo, zieht sie auf einen eigenen Server des Kreises um, und zwar so, dass der Umzug technisch ein Kopiervorgang ist und kein Neuaufbau.

Das Pattern ist keine Theorie. Es ist die dokumentierte Praxis der Referenz-Installation: WJ Konstanz-Hegau (Paten-Kreis, Server "hafen") hat für WJ Hochrhein die Demo wjhcloud.wjknh.de als Docker-Compose-Stack aufgesetzt. Alle Schritte liegen als Scripts im Repo (wj/Nextcloud/wjhcloud-demo/), sind idempotent gebaut und wurden am lebenden System verifiziert. Dieses Kapitel generalisiert diese Scripts zum Runbook.

1. Warum Demo-first

Ein Kreis, der über ein eigenes Digital-System nachdenkt, steht vor einem Henne-Ei-Problem: Ohne laufendes System keine Vorstands-Zustimmung, ohne Zustimmung kein Budget für einen Server. Das Demo-first-Pattern löst das auf, indem der Paten-Kreis die Anlaufkosten trägt: Die Demo läuft als Co-Tenant auf seinem bestehenden Server, braucht keine eigene Hardware und keine eigenen Verträge. Der Interessenten-Kreis bekommt binnen eines Tages eine klickbare, vollständige Instanz mit der Gruppen- und Ordnerstruktur des Standards, Office im Browser (Collabora) und Videokonferenzen (Talk mit High-Performance-Backend).

Drei Grenzen des Patterns, die von Anfang an klar kommuniziert gehören:

  1. Nur Testdaten. Echte Mitgliederdaten kommen erst nach dem Umzug auf einen eigenen Server des Ziel-Kreises in das System. Zwei Vereine sind zwei Verantwortliche im Sinne der DSGVO; die Datentrennung ist keine Formalie, sondern die Bedingung, unter der ein Paten-Kreis überhaupt hosten darf.
  2. Der Paten-Server ist endlich. Auf der Referenz-Installation waren nach dem Aufbau der einen Demo noch 2,7 GB RAM frei; hafen ist damit voll und kann keine weiteren Co-Tenants aufnehmen. Ein Paten-Kreis betreut realistisch eine Demo gleichzeitig, nicht fünf.
  3. Manche Features gibt es erst nach dem Umzug. Die Demo teilt sich Collabora und Talk-HPB mit der Instanz des Paten-Kreises. Was ein eigener Server zusätzlich ermöglicht, steht in Abschnitt 6.

2. Vorab-Entscheidungen (vor dem ersten Kommando)

Vier Fragen muss der Interessenten-Kreis beantworten, bevor der Paten-Kreis das erste Script startet. Sie stammen aus der Hochrhein-Anbahnung und haben sich als die Punkte erwiesen, an denen Rollouts sonst hängen bleiben:

  1. Server-Ownership. Wer besitzt später den Server? Empfehlung: eigener Hetzner-Account des Kreises (Größenordnung 5 bis 10 Euro pro Monat) statt dauerhafter Mitnutzung. Der Account gehört dem Verein, nicht einer Privatperson, sonst ist der nächste Vorstandswechsel ein Infrastruktur-Risiko.
  2. Domain und DNS-Verwaltung. Welche Domain, wer verwaltet die DNS-Zone? Siehe Abschnitt 3, die Antwort bestimmt, wie schmerzhaft der spätere Umzug wird.
  3. Scope. Was gehört in den ersten Ausbau? Der Kern des Standards ist Nextcloud plus Talk-HPB plus Collabora plus Whiteboard. Kompetenz-Hub, eigene n8n-Instanz und Analytics sind kreisspezifische Extras und gehören nicht in den Tag-1-Scope.
  4. Langfrist-Admin. Wer betreut das System nach dem Umzug? Zwei Modelle: zentraler Admin mit SSH-Zugang (etwa der Paten-Kreis oder eine WJD-Struktur) oder der Kreis selbst mit sauberer Übergabe-Doku. Beides ist legitim, aber es muss vor dem Umzug entschieden sein, weil davon Sudo-Konfiguration, Backup-Verantwortung und Update-Betrieb abhängen.

Wenn der Kreis VereinOnline nutzt und die Flow-Automationen (Kapitel n8n) will, gehört eine fünfte Entscheidung dazu: Anlage der VO-Service-User nach dem Least-Privilege-Muster und Setzen der VO-Basiskonfig-Parameter api.getmembers=alle und api.events.alledaten=ja. Beide sind nicht Default; ohne sie liefert die VO-API unvollständige Daten (in der Referenz-Instanz waren es 95 von 162 Mitgliedern, bis der Parameter gesetzt war).

3. Domain-Empfehlung: finale Domain ab Tag 1

Der wichtigste Einzel-Kniff dieses Kapitels: Die Demo läuft von Anfang an unter der Domain, die der Kreis dauerhaft behalten will. Nicht unter demo.paten-kreis.de, nicht unter einer Wegwerf-Subdomain.

Der Grund ist der Umzug. Eine Nextcloud-Instanz hängt an ihrer Domain (Trusted Domains, OIDC-Issuer, Share-Links, Talk-Signaling-Backend, Zertifikate, App-Passwörter in Clients). Bleibt die Domain beim Umzug identisch, reduziert sich der Serverwechsel auf drei mechanische Schritte: Daten rsyncen, Datenbank dumpen und einspielen, DNS-A-Record auf die neue IP drehen. Ändert sich die Domain, wird aus dem Umzug eine Re-Konfiguration mit Nutzer-Sichtbarkeit (neue Login-URL, tote Links, neu einzurichtende Clients).

Konkret heißt das für Tag 0:

4. Tag 1: Die Demo aufsetzen

Voraussetzung auf dem Paten-Server: Ubuntu mit Apache, Docker, certbot, eine laufende Standard-Installation (Nextcloud, Collabora, Talk-HPB) und genug freier RAM für einen weiteren Nextcloud-Stack. Die Scripts liegen in wj/Nextcloud/wjhcloud-demo/ und werden für den neuen Kreis kopiert und parametrisiert (Domain, Instanzname, Port).

Der Ablauf in sechs Schritten, jeweils mit dem Script, das ihn trägt:

Schritt 1: DNS. A-Record der finalen Domain auf die IP des Paten-Servers (Abschnitt 3).

Schritt 2: Stack hochziehen (bootstrap.sh + docker-compose.yml + vhost.conf). Das Root-Bootstrap legt das Instanz-Verzeichnis an (Referenz: /srv/wjhcloud), generiert die .env mit allen Secrets serverseitig via openssl rand (chmod 600, die Werte verlassen den Server nie), startet den Compose-Stack aus nextcloud:stable-apache, postgres:16-alpine und redis:alpine, aktiviert den Apache-vHost (a2ensite plus apache2ctl configtest), wartet per Poll auf status.php mit "installed":true und holt das Let's-Encrypt-Zertifikat via certbot --apache. Der Stack bindet ausschließlich auf 127.0.0.1 (Referenz: Port 8085; Port-Vergabe gegen die Belegungsliste des Servers prüfen, auf hafen war 8090 bereits von PocketBase belegt). Für den Betrieb hinter dem Apache-Proxy setzt das Compose-File OVERWRITEHOST, OVERWRITEPROTOCOL, TRUSTED_PROXIES und APACHE_DISABLE_REWRITE_IP.

Schritt 3: Basiskonfiguration (post-install.sh). Setzt default_phone_region und maintenance_window_start, übernimmt die SMTP-Konfiguration aus der Haupt-Instanz Key für Key (ohne Werte auszugeben) und legt die Admin- und Demo-User mit generierten Passwörtern an (occ user:add --password-from-env). Die Zugangsdaten landen ausschließlich serverseitig in einer chmod-600-Datei, aus der der Paten-Kreis sie dem Ziel-Kreis auf einem sicheren Kanal übergibt.

Schritt 4: Struktur-Setup (setup-demo-11.sh). Das Herzstück, occ via docker exec -u www-data: installiert das volle App-Set des Standards (inkl. richdocuments, spreed, groupfolders, deck, guests), legt die Gruppen des Standard-Modells an, baut die Gruppenordner-Matrix 01_Allgemeines & Vorlagen bis 09_Fotos samt Berechtigungen deckungsgleich zur Referenz nach und bindet Collabora an: Die Demo wird per aliasgroupN-Env an den bestehenden Collabora-Container des Paten-Servers gehängt (Container-Recreate mit erweitertem Env-File, ein Collabora bedient N Instanzen), danach occ config:app:set richdocuments wopi_url und occ richdocuments:activate-config.

Schritt 5: Talk-HPB anbinden (hpb-shared.sh). Der aio-talk-Container des Paten-Servers wird multi-tenant gemacht: /start.sh aus dem Container extrahieren, eine [backend-N]-Sektion mit der Demo-URL hineinpatchen (backends = backend-1, backend-2, ...), Container mit dem gepatchten Script als read-only Overlay-Mount (-v <pfad>:/start.sh:ro) neu erstellen, Env via env-file übernehmen (Secrets bleiben serverseitig). Im vHost der Demo kommt der Signaling-Websocket-Proxy (ProxyPass "/standalone-signaling/" "ws://127.0.0.1:8081/") VOR den generischen ProxyPass /. In der Demo-NC dann occ talk:signaling:add und occ talk:turn:add; TURN braucht keine Backend-Konfiguration, die Shared-Secret-Auth ist domain-agnostisch. Verifikation per curl auf /standalone-signaling/api/v1/welcome für beide Domains. Rollback: Container ohne den Mount neu erstellen. Bekannte Baustelle bei der Generalisierung: Im Referenz-Overlay hat backend-2 keinen eigenen secret =-Eintrag; für den Standard gehört das Secret pro Backend sauber gesetzt bzw. geprüft. Update-Gotcha: Bei Image-Updates des aio-talk-Containers den Mount behalten und /start.sh aus dem neuen Image frisch extrahieren und neu patchen.

Schritt 6: Demo-Inhalte und Verifikation (content/, dav-upload.sh, dav-check.sh). Beispiel-Inhalte per WebDAV-PUT in die Gruppenordner (nicht per docker-cp ins Dateisystem, das indexiert Nextcloud auch mit groupfolders:scan nicht zuverlässig), danach Endkontrolle per WebDAV-PROPFIND und im Browser: Login, Ordner-Sichtbarkeit je Test-User, ein Collabora-Dokument öffnen, einen Talk-Anruf mit Video starten.

Damit steht am Ende von Tag 1 eine vollständige Instanz unter der finalen Domain. Die Referenz hat gezeigt, dass der gesamte Ablauf inklusive Multi-Tenant-Umbau von Collabora und HPB an einem Tag machbar ist, weil jeder Schritt als Script vorliegt.

5. Testphase

Empfehlung: zwei Wochen strukturiertes Testen durch den Interessenten-Kreis, mit Testdaten und einer kleinen Testgruppe (Vorstand plus Digital-Verantwortliche). Was in dieser Zeit passieren sollte:

Für den Paten-Kreis ist die Testphase zugleich eine Frist: Eine Demo, die nach Monaten weder umgezogen noch abgebaut ist, blockiert seinen RAM und seine Betreuungskapazität. Empfehlung: Demo-Laufzeit von vornherein befristen (z. B. auf 4 Wochen) und den Abbau als normalen Ausgang einplanen, falls der Kreis nicht übernimmt.

6. Umzug auf den eigenen Server

Der Umzug ist die Belohnung für die Domain-Disziplin aus Abschnitt 3. Weil die Instanz bereits unter ihrer finalen Domain läuft und alle Daten in benannten Docker-Volumes bzw. der Postgres-DB liegen, ist der Serverwechsel ein Kopiervorgang:

  1. Neuen Server provisionieren. Eigener Cloud-Server des Kreises (Abschnitt 2, Punkt 1), Ubuntu, Apache, Docker, certbot. Achtung, bekannte Lücke des Standards: Diese Grundprovisionierung existiert bislang nur als gelebter Zustand der Referenz, nicht als Script; bis dahin ist sie Handarbeit nach dem Muster des Paten-Servers.
  2. Stack-Definition übertragen. docker-compose.yml, vhost.conf und die serverseitige .env (auf sicherem Weg, nie durch Chat oder Repo) auf den neuen Server kopieren, Stack starten, aber noch nicht öffentlich schalten.
  3. Daten umziehen. Auf dem alten Server die Instanz in den Wartungsmodus setzen, Postgres-Dump ziehen, App- und Daten-Volumes per rsync übertragen, Dump auf dem neuen Server einspielen, Wartungsmodus beenden.
  4. DNS-Flip. Den A-Record der Kreis-Domain von der IP des Paten-Servers auf die neue IP drehen, certbot auf dem neuen Server das Zertifikat holen lassen. Für die Nutzer ändert sich nichts Sichtbares, Login-URL und Links bleiben identisch.
  5. Rückbau beim Paten. Demo-Stack stoppen und nach einer Karenzzeit (Empfehlung: 2 Wochen als Rollback-Fenster) entfernen, HPB-Overlay um das Backend der umgezogenen Instanz bereinigen, Collabora-aliasgroupN zurücknehmen, vHost deaktivieren.
  6. Betrieb einrichten. Erst jetzt, auf dem eigenen Server, kommen echte Mitgliederdaten in das System. Dazu gehört das Betriebs-Fundament der Referenz: nextcloud-autoupdate.sh als täglicher Cron (App-Updates, Core-Point-Releases, Self-Heal bei hängendem Wartungsmodus), unattended-upgrades für das OS, ein Backup-Regime (auf der Referenz gelebte Praxis, als Script noch Repo-Lücke) und der 2FA-Rollout mindestens für Vorstand und Schatzmeister.

7. Was der eigene Server zusätzlich freischaltet

Zwei Fähigkeiten sind auf der geteilten Demo bewusst nicht drin und werden erst nach dem Umzug eingerichtet:

Eigenes Talk-HPB statt Mitnutzung. Auf dem eigenen Server bekommt der Kreis seinen eigenen aio-talk-Container ohne Multi-Tenant-Overlay. Das entkoppelt ihn vom Paten-Server (kein gemeinsamer Ausfallpunkt, keine geteilten Signaling-Secrets) und macht künftige Updates auf beiden Seiten einfacher, weil das Overlay-Patch-Muster entfällt. Gleiches gilt für Collabora: eigene Instanz statt aliasgroupN-Eintrag beim Paten.

Recording und lokale Transkription. Ein Recording-Backend für Talk plus lokales Whisper-Speech-to-Text braucht in der Größenordnung 8 GB RAM und passt damit nicht als Co-Tenant auf einen ausgelasteten Paten-Server. Wichtig für die Positionierung des Standards: Die Transkription läuft lokal auf dem Kreis-Server. Externe STT-APIs widersprechen dem Souveränitäts-Versprechen des Systems ("euer Audio verlässt nie euren Server"), und die günstigen Inference-Angebote der Hoster können kein Audio. Wer Transkription will, plant den Server entsprechend größer.

8. Kostenrahmen

Belegte Zahl aus der Referenz-Praxis: Ein eigener Hetzner-Cloud-Server für den Kern-Stack liegt bei etwa 5 bis 10 Euro pro Monat. Alles Weitere ist Empfehlung, keine erhobene Zahl:

9. Bekannte Lücken dieses Runbooks

Ehrlichkeit gehört in einen Standard. Vier Punkte deckt der heutige Code-Stand noch nicht ab, sie sind Handarbeit oder offene Aufgabe:

  1. Die Server-Grundprovisionierung (Ubuntu, Apache, Docker, Firewall, certbot) existiert nur als gelebter Zustand der Referenz, nicht als Script.
  2. Kreis-spezifische Werte (Domain, Kreisname, Usernamen, Gruppen-Leads) sind in den Scripts teilweise hart codiert und müssen bei jedem Rollout von Hand parametrisiert werden.
  3. Das HPB-Overlay-Patch skaliert nur additiv (awk-Patch pro Backend); ab mehreren gleichzeitigen Demos braucht es eine saubere Config-Generierung, inklusive Secret pro Backend.
  4. Backup und Offsite-Kopie sind dokumentierte Praxis der Referenz, aber ohne Repo-Artefakt; das Umzugs-Kapitel setzt einen manuellen DB-Dump voraus.

Checkliste

Vorab (Tag 0):

Tag 1 (Demo):

Testphase:

Umzug:

Referenz KNH

So läuft das Pattern bei Konstanz-Hegau konkret (Stand 2026-08-13):

← 06 BetriebWeiter: 08 Server →