Deployment und Freigabe

DiGeKo benötigt keine bestimmte Hostingplattform. App und CMS sind getrennte Node.js-Dienste und können auf einer VM, in Containern oder auf einer Application Platform betrieben werden.

Voraussetzungen für eine eigene Produktion

• zwei HTTPS-Adressen: eine für die öffentliche App und eine für das CMS
• Node.js 24 und pnpm für die App
• Node.js 20 bis 22 und npm für das CMS
• eine MySQL-Datenbank
• einen S3-kompatiblen Medienspeicher; lokaler Upload ist im NODE_ENV=production absichtlich gesperrt
• einen vollständig konfigurierten TTS-Anbieter
• einen SMTP-Dienst mit verifizierter Absenderadresse für transaktionale CMS-E-Mails
• bei aktivierten Bildvorschlägen einen vollständig konfigurierten Bildanbieter und einen eigenen privaten Vorschlags-Bucket
• persistente Backups von Datenbank und Medien

App bereitstellen

1. App-Repository klonen und den gewünschten Commit oder Tag auschecken.
2. mindestens NEXT_PUBLIC_CMS_URL und NEXT_PUBLIC_INFO_CATEGORY_DOCUMENT_ID setzen; Preview-Variablen nur bei Bedarf ergänzen. Bei aktivierter Vorschau muss APP_ORIGIN den öffentlichen Origin der App enthalten.
3. pnpm install --frozen-lockfile und pnpm build ausführen.
4. den Build mit pnpm start hinter einem HTTPS-Reverse-Proxy starten.

Öffentliche NEXT_PUBLIC_*-Werte werden in den Build eingebettet. Nach einer Änderung ist deshalb ein neuer App-Build erforderlich.

CMS bereitstellen

1. CMS-Repository klonen und den gewünschten Commit oder Tag auschecken.
2. Strapi-Secrets, MySQL, S3, SMTP, Preview, TTS und optional Bildvorschläge über Umgebungsvariablen konfigurieren.
3. npm ci, npm run build und anschließend npm run start ausführen.
4. optional den veröffentlichten Ausgangsdatenstand in eine frische Instanz importieren.
5. Healthcheck, CMS-Anmeldung, transaktionale E-Mails, Preview, Medienupload, TTS, aktivierte Bildvorschläge und App-Abruf prüfen.

Transaktionale CMS-E-Mails

Das CMS versendet über Strapis E-Mail-Plugin zwei Arten administrativer Nachrichten:

• Strapis Funktion „Passwort vergessen“ sendet den Link zum Zurücksetzen des Admin-Passworts.
• Beim Anlegen eines noch nicht aktiven Admins sendet das CMS automatisch den persönlichen Registrierungslink.

Der von Strapi angezeigte, kopierbare Registrierungslink bleibt als Fallback erhalten. Ein fehlgeschlagener Versand löscht weder den Admin noch dessen Token; das Serverlog nennt nur einen technischen Fehlercode. Ein eigener Resend-Endpunkt ist nicht Bestandteil des CMS. Er würde zusätzliche Missbrauchsbegrenzung und Auditierung benötigen.

PUBLIC_URL muss auf die von den Empfänger:innen erreichbare CMS-Origin ohne /admin zeigen. SMTP-Verbindung, Absender und Zugangsdaten werden über die CMS-Umgebungsvariablen gesetzt. Direkte TLS-Verbindungen verwenden üblicherweise Port 465 mit SMTP_SECURE=true; bei STARTTLS sind Port und SMTP_SECURE nach den Angaben des Providers zu wählen.

Für die Zustellbarkeit sind außerhalb des CMS mindestens folgende Punkte zu prüfen. Mailprovider können diese Einträge für ihre eigenen Mailserver bereits verwalten; vorhandene Einträge werden nicht ungeprüft überschrieben:

• Absenderadresse oder Absenderdomain beim Mailprovider verifizieren;
• kontrollieren, dass der vorhandene SPF-Eintrag den verwendeten SMTP-Server autorisiert; pro Domain darf nur ein SPF-Eintrag existieren;
• kontrollieren, dass DKIM für den SMTP-Anbieter aktiv ist und der zugehörige öffentliche Schlüssel im DNS erreichbar ist;
• die vorhandene DMARC-Policy prüfen und erst nach erfolgreicher Abnahme gezielt verschärfen.

Nach einer Änderung an SMTP, DNS oder öffentlicher CMS-URL umfasst die Staging-Abnahme:

1. unter Settings → Email feature → Configuration eine Testmail senden;
2. abgemeldet „Passwort vergessen“ ausführen und Zustellung sowie Reset-Linkziel prüfen;
3. einen noch nicht aktiven Admin einladen und Zustellung sowie Registrierungs-Linkziel prüfen;
4. den kopierbaren Link als Fallback kontrollieren;
5. mit absichtlich ungültiger SMTP-Konfiguration in einer Testumgebung prüfen, dass nur ein technischer Fehlercode protokolliert wird und der Link erhalten bleibt.

Zugangsdaten gehören ausschließlich in geschützte Laufzeit-Secrets. Sie dürfen weder committed, als Container-Build-Argument verwendet noch durch ein öffentliches Variablenpräfix in das Admin-Bundle übernommen werden.

Docs bereitstellen

1. Docs-Repository klonen und den gewünschten Commit oder Tag auschecken.
2. NEXT_PUBLIC_DOCS_ENV und NEXT_PUBLIC_SITE_URL passend zur Zielumgebung setzen.
3. pnpm install --frozen-lockfile und pnpm build ausführen.
4. den Standalone-Build mit pnpm start hinter einem HTTPS-Reverse-Proxy starten.
5. direkten Seitenaufruf, Navigation, Suche und Robots-Metadaten prüfen.

Umgebungsvariablen nachschlagen →

Öffentlichen Datenexport importieren →

Versionen und Kompatibilität →

Projektbetrieb mit Coolify

Die offiziellen DiGeKo-Umgebungen werden derzeit durch Coolify aus den jeweiligen GitLab-Repositories gebaut. Die Docs-Ressourcen verwenden den Build Pack Nixpacks. Nixpacks erkennt die package.json-Scripts und erzeugt den Buildcontainer; ein Dockerfile im Repository ist dafür nicht erforderlich. Ein Wechsel zum Dockerfile-Build-Pack wäre eine bewusste, separate Betriebsentscheidung.

Konkrete Staging-Adressen, Deployment-Auslöser, Ressourcenkennungen, Konfigurationswerte und Eskalationskontakte stehen ausschließlich im internen Betriebshandbuch. Sie sind für Mitwirkende und für den Betrieb einer eigenen Installation nicht erforderlich.

GitLab CI prüft den Quellstand. Coolify steuert Build, Runtime-Variablen und Deployment der freigegebenen Branches.

Rollen

• Mitentwickler:innen liefern kleine, prüfbare Merge Requests, führen die relevanten Tests aus und dokumentieren Auswirkungen auf App, CMS und Docs.
• Maintainer:innen/Projektverantwortliche prüfen Merge Request und CI, nehmen das Ergebnis auf Staging ab, entscheiden über die Freigabe nach main, beobachten das Deployment und führen die nachgelagerte Smoke-Prüfung durch. Bei einem Fehler entscheiden sie über Abbruch, erneutes Deployment oder Rollback.

Konkrete Personen, Vertretungen und Kontaktwege werden nur im internen Betriebshandbuch gepflegt.

Reguläre Freigabe

1. Mitentwickler:innen stellen abgeschlossene Änderungen im Status Abnahme mit einem Merge Request nach dev bereit.
2. Maintainer:innen nehmen sie ab, mergen nach dev und verschieben die Issues nach Release.
3. App, CMS und Docs auf Staging bauen und die integrierten automatischen und manuellen Prüfungen durchführen.
4. Zum vorgesehenen Release-Zeitpunkt Merge Requests von dev nach main erstellen.
5. Bei gekoppelten Änderungen zuerst CMS, dann App, zuletzt Docs deployen.
6. Produktions-Smoke-Test durchführen und veröffentlichte Issues schließen.
7. Projekt-Release mit den tatsächlich eingesetzten Komponentenständen dokumentieren.

Das öffentliche Versionsmodell und die Auswahl gemeinsam getesteter Komponenten- und Datenstände stehen unter Versionen und Kompatibilität.

Docs werden zuletzt veröffentlicht, damit digeko.de keine noch nicht produktive Funktion beschreibt.

Zusammenspiel von App und CMS

App und CMS bilden je Zielumgebung ein festes Paar. Die App lädt veröffentlichte Inhalte aus dem über CMS_URL beziehungsweise NEXT_PUBLIC_CMS_URL zugeordneten CMS. Für die Vorschau verweist das CMS über PREVIEW_FRONTEND_URL zurück auf die zugehörige App. Der serverseitige APP_ORIGIN der App muss diesem öffentlichen Origin entsprechen. Konfigurationen von Staging und Produktion dürfen nicht miteinander gekreuzt werden.

Content- und API-Vertrag →

Content Preview und Sicherheitsgrenze →

Healthcheck und Smoke-Prüfung

Ein technischer Healthcheck prüft ohne Anmeldung, ob der jeweilige Prozess über HTTPS erreichbar ist und mit dem erwarteten erfolgreichen HTTP-Status oder einer vorgesehenen Weiterleitung antwortet. Er ersetzt keine fachliche Smoke-Prüfung.

Nach jedem Deployment werden mindestens diese Punkte geprüft:

Bei Änderungen an Medien, TTS, Datenmodell oder Deploymentkonfiguration werden die betroffenen Pfade zusätzlich geprüft. Wiederkehrende Laufzeitfehler in den Logs, fehlerhafte Abhängigkeiten oder nicht passende Komponentenstände machen das Deployment nicht freigabefähig.

Bei Änderungen am TTS-Zugriffsschutz wird außerdem geprüft, dass eine Admin-UI-Aktion mit passender Content-Manager-Berechtigung funktioniert und dieselbe Route ohne Admin-Session 401 sowie mit fehlender Berechtigung 403 liefert. Weder Reverse Proxy noch Netzwerksegmentierung dürfen dabei die anwendungsseitige Session- und RBAC-Prüfung ersetzen.

Bei aktivierten Bildvorschlägen umfasst die Staging-Prüfung mindestens je einen deutschen und englischen Auftrag: Vorschläge erzeugen, abbrechen oder erneut starten, vergleichen, Alternativtext prüfen, genau einen Vorschlag übernehmen, den Entwurf speichern und die Darstellung in der App kontrollieren. Nicht ausgewählte Vorschläge dürfen nicht in der Media Library erscheinen. Vor einem Shutdown wird kontrolliert, dass ein laufender Job beim nächsten Start wieder aufgenommen wird. Bei fal.ai muss dabei dieselbe gespeicherte Provider-Request-ID weiterverwendet werden, damit kein zweiter kostenpflichtiger Auftrag entsteht. Das mit AI_IMAGE_RATE_LIMIT_MAX konfigurierte Limit für verändernde Bildanfragen wird ebenfalls geprüft. Es gilt je Route, Client-IP und CMS-Instanz innerhalb von 60 Sekunden; mehrere Instanzen benötigen für ein globales Limit zusätzlich eine gemeinsame Begrenzung am Reverse Proxy. IMAGE_GENERATION_ENABLED=false ist der betriebliche Abschaltweg ohne Codeänderung. Providerpreise werden nicht fest im CMS hinterlegt. Eine angezeigte Kostenschätzung muss vor der Produktionsfreigabe gegen die aktuelle Abrechnung des Betreibers geprüft werden; sie ist weder Rechnung noch Budget.

Branch-Schutz

main und dev werden gegen direkte Pushes und Force Push geschützt. Änderungen laufen über Merge Requests und benötigen eine grüne relevante CI. Produktion wird ausschließlich aus main, Staging ausschließlich aus dev gebaut.

Hotfix

Ein Produktions-Hotfix zweigt von main ab, wird nach Prüfung dorthin zurückgeführt und anschließend auch nach dev übernommen. Betroffene Dokumentation folgt demselben Weg.

Rollback

Ein Code-Rollback verwendet den letzten nachweislich funktionierenden Commit, Tag oder dokumentierten Release-Stand:

1. fehlerhaften Stand und beobachtete Auswirkungen festhalten;
2. letzten funktionierenden Stand mit unveränderter Zielkonfiguration erneut bauen und bereitstellen;
3. bei gekoppelten Änderungen die Reihenfolge CMS, App und zuletzt Docs beachten;
4. Healthcheck und Smoke-Prüfung vollständig wiederholen;
5. Korrektur anschließend wieder in die regulären Branches übernehmen.

Ein Code-Rollback setzt weder Inhalte noch Datenbank, Medien oder Konfigurationszustände zurück. Schema- und Datenänderungen benötigen deshalb vor der Freigabe einen getrennten Rückweg. Die konkrete Sicherung und Wiederherstellung der offiziellen Umgebungen ist Teil des internen Betriebshandbuchs und wird nicht öffentlich beschrieben.