HedgeDoc 2026 selbst hosten: WebSockets, OAuth und hochgeladene Dateien

Es gibt zwei Varianten, HedgeDoc zu „betreiben“: Ein Container ist vorhanden oder der Dienst erfüllt tatsächlich seine Aufgabe. Nur die zweite Variante zählt. Der Beweis besteht hier darin, eine Notiz zu erstellen, sie gleichzeitig in zwei Browsern zu bearbeiten, ein Bild hochzuladen und sich über den ausgewählten Provider zu authentifizieren.

HedgeDoc erfüllt genau diesen Zweck: kollaborative Markdown-Notizen in Echtzeit. Die Bereitstellung muss die Komponenten hinter diesem Verhalten erhalten. Ein Port, ein Volume und ein Zertifikat sind Eingaben, nicht das Ergebnis.

Den Zustand sichern, den HedgeDoc nicht wiederherstellen kann

Definieren Sie den Recovery Point und die Recovery Time für HedgeDoc anhand der Datenbank, der hochgeladenen Dateien und der Authentifizierungskonfiguration. Mounten Sie /hedgedoc/public/uploads vor dem Bootstrap, schreiben Sie harmlose Beispieldaten und ersetzen Sie den Container, um zu beweisen, dass dieser Pfad tatsächlich persistent ist. Ein benanntes Volume stellt die Persistenz bei erneuten Deployments sicher, schützt aber weder vor einer Kompromittierung noch vor dem Verlust des Servers.

Erstellen Sie eine saubere Restore-Umgebung, verwenden Sie dieselbe festgelegte Anwendungsversion und weisen Sie nach, dass Notizen, Revisionen, Benutzer und Uploads wieder vorhanden sind und zwei Browser auf der wiederhergestellten Notiz zusammenarbeiten können. Dokumentieren Sie Befehle, Anpassungen von Besitzrechten und die verstrichene Zeit. Der Backup-Leitfaden bietet dafür einen nützlichen Standard: Ein Backup gilt erst nach der Wiederherstellung als vertrauenswürdig, nicht bereits nach dem Upload.

HedgeDoc von seinen Abhängigkeiten trennen

Prozesszustand und Produktzustand sind bei HedgeDoc zwei verschiedene Dinge. Port 3000 kann antworten, während die Transaktion aus Sicht des Benutzers weiterhin fehlschlägt. Der Netzwerkvertrag für HedgeDoc umfasst Postgres sowie optionale OAuth- und SMTP-Provider. Halten Sie private Endpunkte in internem DNS, erlauben Sie nur die erforderlichen ausgehenden Verbindungen und geben Sie HedgeDoc ein Service-Credential mit begrenzten Berechtigungen.

Verwenden Sie diese Readiness-Prüfung nach wesentlichen Konfigurationsänderungen: Erstellen Sie eine Notiz, bearbeiten Sie sie gleichzeitig in zwei Browsern, laden Sie ein Bild hoch und authentifizieren Sie sich über den ausgewählten Provider. Halten Sie aufwendige externe Prüfungen aus Liveness-Probes heraus, damit ein Ausfall eines Providers keine Restart-Schleife auslöst. Bei der Kapazitätsplanung sollten Sie WebSocket-Verbindungen, Datenbankschreibvorgänge, hochgeladene Medien und die Dokumenthistorie überwachen. Diese Größen bilden die tatsächliche Belastung von HedgeDoc besser ab als Seitenaufrufe.

Fünf Prüfungen, die aussagekräftiger sind als der Container-Healthcheck

Machen Sie aus dem HedgeDoc-Smoke-Test einen wiederholbaren Release-Befehl oder ein kurzes Runbook. Die Ausgabe muss dieses Ergebnis nachweisen: Erstellen Sie eine Notiz, bearbeiten Sie sie gleichzeitig in zwei Browsern, laden Sie ein Bild hoch und authentifizieren Sie sich über den ausgewählten Provider. Erfassen Sie zusammen mit dem Ergebnis die Anwendungsversion, den Container-Digest, den Hostnamen der Route und die Kennung der Testdaten.

Führen Sie dieselbe Prüfung nach einem routinemäßigen Container-Austausch sowie nach der Wiederherstellung von Datenbank, hochgeladenen Dateien und Authentifizierungskonfiguration an einem anderen Ort durch. Die Wiederherstellung war erfolgreich, wenn Notizen, Revisionen, Benutzer und Uploads wieder vorhanden sind und zwei Browser auf der wiederhergestellten Notiz zusammenarbeiten können. Vergleichen Sie Zeitaufwand und Verbrauch im Zusammenhang mit WebSocket-Verbindungen, Datenbankschreibvorgängen, hochgeladenen Medien und der Dokumenthistorie. Eine deutliche Veränderung sollte untersucht werden, selbst wenn die abschließende Aktion weiterhin erfolgreich ist.

Testen Sie anschließend einen sicheren Fehlerfall: Verweigern Sie der Testidentität vorübergehend den Zugriff auf Postgres sowie auf optionale OAuth- und SMTP-Provider. Stellen Sie sicher, dass HedgeDoc den Fehler sichtbar macht und ohne destruktive manuelle Änderungen zum Normalbetrieb zurückkehrt. Bewahren Sie nur den erforderlichen, bereinigten Log-Ausschnitt auf. Dieses vierteilige Gate deckt Start, Persistenz, Wiederherstellung und Fehlerbehandlung ab.

HedgeDoc starten, ohne die beweglichen Teile zu verbergen

Ein minimaler Befehl ist nützlich, wenn er sichtbar macht, was die Plattform später verwalten wird.

docker run -d \
  --name hedgedoc \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v hedgedoc-data:/hedgedoc/public/uploads \
  -e CMD_SESSION_SECRET=replace-with-a-long-random-value \
  -e CMD_DOMAIN=app.example.com \
  -e CMD_PROTOCOL_USESSL=true \
  -e CMD_DB_URL=postgres://hedgedoc:replace-password@postgres.internal:5432/hedgedoc \
  quay.io/hedgedoc/hedgedoc:latest

Hier bleibt Port 3000 nur für den Host erreichbar, und jeder erforderliche Pfad ist explizit angegeben. Ergänzen Sie die geprüften Verbindungseinstellungen für Postgres sowie optionale OAuth- und SMTP-Provider. Verwenden Sie für private Dienste private Namen. Prüfen Sie den Start sowohl anhand der Logs als auch mit dem anwendungsspezifischen Nachweis: Erstellen Sie eine Notiz, bearbeiten Sie sie gleichzeitig in zwei Browsern, laden Sie ein Bild hoch und authentifizieren Sie sich über den ausgewählten Provider. Sobald alles geprüft ist, pinnen Sie die Image-Version, damit ein routinemäßiger Austausch das Verhalten nicht unbemerkt verändert.

Geben Sie HedgeDoc nicht den gesamten Host

Bei HedgeDoc ist die wertvolle Angriffsfläche nicht unbedingt die Landingpage. Der häufigste Fehler besteht darin, ein Beispiel-Session-Secret zu verwenden oder unbeabsichtigt das anonyme Erstellen von Notizen zu erlauben. Beugen Sie dem gezielt vor: Verwenden Sie ein stabiles Session-Secret, entscheiden Sie, ob das anonyme Erstellen von Notizen akzeptabel ist, und beschränken Sie den Zugriff auf private Notizen.

Generieren Sie CMD_SESSION_SECRET als langen zufälligen Wert. Eine Rotation macht Sessions oder Tokens normalerweise ungültig. Planen Sie daher die Auswirkungen auf Benutzer, statt dies als Migration der Verschlüsselung zu behandeln. Verwenden Sie einen unprivilegierten Container-Benutzer, sofern das Image dies unterstützt, und mounten Sie keine nicht benötigten Credentials. Setzen Sie am Ingress Raten- oder Größenlimits, da nicht vertrauenswürdige Vorgänge WebSocket-Verbindungen, Datenbankschreibvorgänge, hochgeladene Medien und die Dokumenthistorie belasten können.

HedgeDoc von außerhalb des Servers testen

Legen Sie den endgültigen HedgeDoc-Hostnamen fest, bevor Benutzer Callback- oder Client-Einstellungen speichern, und setzen Sie CMD_DOMAIN und CMD_PROTOCOL_USESSL auf die öffentliche URL. Die Plattform-Route sollte TLS einmal terminieren und auf den privaten Port 3000 weiterleiten.

Führen Sie die Akzeptanztransaktion von außerhalb aus. Wenn der Client HedgeDoc nie erreicht, verwenden Sie die Checkliste zur SSL-Validierung für DNS- und Zertifikatsprüfungen. Wenn die Anfrage HedgeDoc erreicht, die Echtzeitbearbeitung aber aufgrund fehlerhafter WebSockets oder Domain-Einstellungen fehlschlägt, ändern Sie nicht weiter Proxy-Redirects, sondern untersuchen Sie stattdessen die anwendungsspezifische Grenze.

HedgeDoc rund um seinen tatsächlichen Engpass betreiben

Verwenden Sie „eine Notiz erstellen, sie gleichzeitig in zwei Browsern bearbeiten, ein Bild hochladen und sich über den ausgewählten Provider authentifizieren“ nach jedem Deployment als HedgeDoc-Smoke-Test. Die zugehörigen Metriken sind WebSocket-Verbindungen, Datenbankschreibvorgänge, hochgeladene Medien und die Dokumenthistorie. Lösen Sie Alerts dort aus, wo sich diese Ressourcen einem Punkt nähern, an dem die Benutzeraktion beeinträchtigt wird.

Das größte Änderungsrisiko besteht darin, dass HedgeDoc-Datenbankmigrationen, OAuth-Einstellungen sowie Änderungen an Plugins oder Renderern einen stufenweisen Release benötigen. Ein sicherer Release beginnt mit einem wiederherstellbaren Snapshot und validiert jede einseitige Zustandsänderung, bevor Datenverkehr weitergeleitet wird. Wenn die Echtzeitbearbeitung aufgrund fehlerhafter WebSockets oder Domain-Einstellungen fehlschlägt, lassen Sie den fehlerhaften Container lange genug bestehen, um seine Konfiguration und den ersten Fehler zu lesen.

Wie Dockup Arbeit für HedgeDoc reduziert

Dockup kann die austauschbaren Plattformkomponenten übernehmen: Datenverkehr an Port 3000 weiterleiten, Domain und Zertifikat ausstellen, Secrets injizieren, persistenten Speicher anbinden und HedgeDoc mit verwalteten oder privat angebundenen Diensten verbinden. Dies ist sowohl auf der Dockup-Infrastruktur als auch auf einem von Ihnen angebundenen Server möglich.

Die Abnahmearbeit für HedgeDoc bleibt explizit. Setzen Sie nach dem One-Click-Deployment CMD_DOMAIN und CMD_PROTOCOL_USESSL auf die öffentliche URL, verbinden und testen Sie Postgres sowie optionale OAuth- und SMTP-Provider und führen Sie dieses Szenario aus: Erstellen Sie eine Notiz, bearbeiten Sie sie gleichzeitig in zwei Browsern, laden Sie ein Bild hoch und authentifizieren Sie sich über den ausgewählten Provider. Diese Aufteilung ist beabsichtigt: Dockup beseitigt wiederholte Infrastrukturarbeit, ohne vorzugeben, dass sich Anwendungsrollen, Provider-Credentials oder die Restore-Strategie von selbst festlegen.

Häufig gestellte Fragen

Was benötigt HedgeDoc für ein produktives Deployment?

Leiten Sie den HedgeDoc-Container über einen HTTPS-Origin an Port 3000 weiter. Die unterstützende Netzwerkanforderung umfasst Postgres sowie optionale OAuth- und SMTP-Provider. Erklären Sie HedgeDoc erst dann für bereit, wenn Sie eine Notiz erstellen, sie gleichzeitig in zwei Browsern bearbeiten, ein Bild hochladen und sich über den ausgewählten Provider authentifizieren können.

Welche HedgeDoc-Daten gehören in ein Backup?

Persistieren Sie /hedgedoc/public/uploads und nehmen Sie Datenbank, hochgeladene Dateien und Authentifizierungskonfiguration in dasselbe Recovery-Manifest auf. Ein sauberes HedgeDoc-Restore ist erst dann erfolgreich, wenn Notizen, Revisionen, Benutzer und Uploads wieder vorhanden sind und zwei Browser auf der wiederhergestellten Notiz zusammenarbeiten können.

Benötigt HedgeDoc HTTPS hinter einem Reverse Proxy?

Verwenden Sie HTTPS für den öffentlichen HedgeDoc-Origin und halten Sie Port 3000 auf der internen Route. Wenden Sie die HedgeDoc-Einstellung korrekt an: Setzen Sie CMD_DOMAIN und CMD_PROTOCOL_USESSL auf die öffentliche URL. Bei HedgeDoc schützt HTTPS Credentials und Benutzerinhalte während der Übertragung und sorgt dafür, dass originabhängiges Client-Verhalten konsistent bleibt.

Wie sollte ein HedgeDoc-Upgrade getestet werden?

Stellen Sie den aktuellen HedgeDoc-Zustand in einem isolierten Deployment wieder her, spielen Sie die Kandidatenversion ein und wiederholen Sie die Akzeptanztransaktion. Achten Sie besonders darauf, da HedgeDoc-Datenbankmigrationen, OAuth-Einstellungen sowie Änderungen an Plugins oder Renderern einen stufenweisen Release benötigen. Behalten Sie das vorherige HedgeDoc-Image, bis die Grenzen der Datenmigration und des Rollbacks verstanden sind.