HedgeDoc: gemeinsame Markdown-Notizen in Echtzeit

Ein Etherpad, das Markdown kann: Zwei Leute tippen gleichzeitig in dieselbe Notiz, rechts entsteht live die formatierte Fassung, und am Ende verschickst du einen Link. HedgeDoc macht genau das – und liefert dabei ein paar Voreinstellungen mit, die du kennen solltest, bevor die Notiz im Netz steht.

Was bauen wir?

Wir betreiben HedgeDoc 1.12.0 mit PostgreSQL 18.6 hinter Traefik. Am Ende hast du einen Editor, in dem mehrere Leute gleichzeitig an derselben Markdown-Notiz arbeiten, mit Tabellen, Aufgabenlisten und einer Live-Vorschau. Notizen lassen sich als Link weitergeben – lesend oder schreibend, ganz wie du es einstellst.

Der zweite Teil ist wichtiger als der erste: HedgeDoc kommt offen aus der Kiste. Jeder darf sich registrieren, und jeder Besucher darf Notizen anlegen – auch ohne Konto. Wir drehen das um – geschlossen als Grundzustand, geöffnet pro Notiz – und schauen dabei genau hin, weil zwei der Einstellungen nicht das tun, was ihr Name verspricht.

Voraussetzungen

• Traefik als Reverse Proxy mit funktionierendem Let’s-Encrypt-Resolver und einer Domain, die auf den Server zeigt
• Die Domain musst du vorher kennen: HedgeDoc baut alle Links aus einer fest konfigurierten Domain, nachträgliches Umziehen ist unangenehm
• Etwa 1 GB freier Arbeitsspeicher für Anwendung und Datenbank zusammen

Schritt für Schritt

Schritt 1: Der Stack – mit einer aktuellen Postgres-Falle

mkdir -p /opt/hedgedoc && cd /opt/hedgedoc

Zuerst die Geheimnisse. HedgeDoc signiert damit die Sitzungs-Cookies; ohne eigenen Wert nimmt es einen zufälligen, und alle Anmeldungen fliegen bei jedem Neustart raus:

umask 077
{
  echo "POSTGRES_PASSWORD=$(openssl rand -base64 24 | tr -d '=+/' | cut -c1-24)"
  echo "CMD_SESSION_SECRET=$(openssl rand -hex 32)"
} > .env

# /opt/hedgedoc/compose.yaml
services:
  database:
    image: postgres:18.6-alpine
    container_name: hedgedoc-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: hedgedoc
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: hedgedoc
    volumes:
      - pgdata:/var/lib/postgresql
    networks: [hedgedoc-intern]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U hedgedoc"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: quay.io/hedgedoc/hedgedoc:1.12.0
    container_name: hedgedoc
    restart: unless-stopped
    depends_on:
      database:
        condition: service_healthy
    environment:
      CMD_DB_URL: postgres://hedgedoc:${POSTGRES_PASSWORD}@database:5432/hedgedoc
      CMD_SESSION_SECRET: ${CMD_SESSION_SECRET}
      CMD_DOMAIN: DEINE_DOMAIN
      CMD_PROTOCOL_USESSL: "true"
      CMD_URL_ADDPORT: "false"
      CMD_ALLOW_EMAIL_REGISTER: "false"
      CMD_ALLOW_ANONYMOUS: "false"
      CMD_DEFAULT_PERMISSION: "limited"
      CMD_ALLOW_FREEURL: "true"
    volumes:
      - ./uploads:/hedgedoc/public/uploads
    networks: [hedgedoc-intern, proxy]
    labels:
      - traefik.enable=true
      - traefik.http.routers.hedgedoc.rule=Host(`DEINE_DOMAIN`)
      - traefik.http.routers.hedgedoc.entrypoints=websecure
      - traefik.http.routers.hedgedoc.tls.certresolver=le
      - traefik.http.services.hedgedoc.loadbalancer.server.port=3000

volumes:
  pgdata:

networks:
  hedgedoc-intern:
    internal: true
  proxy:
    external: true

Zwei Dinge an diesem Stack sind kein Zufall. Die Datenbank hängt in einem eigenen, internen Netz (internal: true) und ist damit weder von außen noch von anderen Containern im proxy-Netz erreichbar – nur HedgeDoc, das in beiden Netzen steckt, kommt heran. Und der healthcheck samt depends_on: condition: service_healthy verhindert, dass HedgeDoc startet, bevor Postgres bereit ist; sonst bricht es beim ersten Verbindungsversuch ab.

Warum ein benanntes Volume und kein ./pgdata-Ordner? Weil ein Bind-Mount am neuen Pfad dem Container gehören muss und sonst mit mkdir: can't create directory '/var/lib/postgresql/18/': Permission denied scheitert – beim alten Pfad hat das Image das noch selbst geradegezogen. Für Backups brauchst du den Ordner ohnehin nicht: Ein Datenbank-Backup macht man mit pg_dump, nicht mit einer Dateikopie.

Schritt 2: Die Variablen, die über Links und Sicherheit entscheiden

Vier davon betreffen die Adressen, die HedgeDoc erzeugt:

• CMD_DOMAIN – deine Domain, ohne Protokoll und ohne Pfad. Fehlt sie, stehen in verschickten Links localhost.
• CMD_PROTOCOL_USESSL: "true" – erzeugt https://-Links. Der Container selbst spricht weiter HTTP, das TLS macht Traefik.
• CMD_URL_ADDPORT: "false" – ohne das hängt HedgeDoc einen Port an jede URL.
• CMD_ALLOW_FREEURL: "true" – erlaubt sprechende Adressen wie /kochabend statt einer Zufalls-ID: Wer eine noch freie Adresse aufruft, legt dort eine neue Notiz an. Mit der nächsten Einstellung gilt das nur für angemeldete Nutzer.

Die anderen drei entscheiden, wer überhaupt hereinkommt:

• CMD_ALLOW_EMAIL_REGISTER: "false" – niemand kann sich selbst registrieren. Konten legst du auf der Kommandozeile an (Schritt 4).
• CMD_ALLOW_ANONYMOUS: "false" – Gäste dürfen keine Notizen anlegen. Der Name führt in die Irre: Lesen dürfen Gäste trotzdem, sofern die jeweilige Notiz das erlaubt (Schritt 6). Steht der Wert auf true – so ist es ab Werk –, legt jeder Besucher über New oder eine freie Adresse Notizen an, die niemandem gehören und für jeden bearbeitbar sind. Bots, die das Netz nach WordPress absuchen, erzeugen so schon in den ersten Minuten Notizen wie /wp-json und /xmlrpc.php. Nebenbei dürfen mit false nur noch angemeldete Nutzer Bilder hochladen.
• CMD_DEFAULT_PERMISSION: "limited" – neue Notizen sind für Gäste zu. Öffnen tust du sie einzeln. Diese Vorgabe gilt nur für Notizen mit Besitzer; eine Gast-Notiz steht immer auf „Freely“ – ein Grund mehr für CMD_ALLOW_ANONYMOUS: "false".

Schritt 3: Starten und nachsehen, ob es dicht ist

docker compose up -d
docker compose ps

NAME          STATUS
hedgedoc      Up 25 seconds (healthy)
hedgedoc-db   Up 50 seconds (healthy)

Beide Container melden healthy – die Datenbank antwortet auf pg_isready, HedgeDoc auf seinen eigenen Healthcheck. Jetzt die Gegenprobe von außen. HedgeDoc hat einen offenen Status-Endpunkt, der sich gut zum Prüfen eignet:

curl -s https://DEINE_DOMAIN/status

{"onlineNotes":0,"onlineUsers":0,"distinctOnlineUsers":0,"notesCount":0,"registeredUsers":0, …}

Und die drei Türen, die zu sein sollen:

curl -s -o /dev/null -w "register: %{http_code}\n" -X POST https://DEINE_DOMAIN/register
curl -s -o /dev/null -w "neue Notiz: %{http_code} %{redirect_url}\n" https://DEINE_DOMAIN/new
curl -s -o /dev/null -w "freie URL: %{http_code} %{redirect_url}\n" https://DEINE_DOMAIN/kochabend

register: 404
neue Notiz: 302 https://DEINE_DOMAIN/
freie URL: 302 https://DEINE_DOMAIN/

404 heißt: Die Registrierungsroute existiert gar nicht mehr. Bei /new und der freien Adresse kommt es auf das Ziel der Weiterleitung an: Die Startseite heißt, der Gast wurde weggeschickt. Zeigt die Weiterleitung dagegen auf eine neue Adresse wie https://DEINE_DOMAIN/JBdRlegoRAqN… oder https://DEINE_DOMAIN/kochabend, hat HedgeDoc gerade eine Notiz angelegt – dann steht CMD_ALLOW_ANONYMOUS noch auf true. Die Gegenprobe ist notesCount im Status-Endpunkt: Der muss bei 0 bleiben, solange du selbst nichts angelegt hast.

Schritt 4: Ein Konto anlegen – auf der Kommandozeile

Weil die Selbstregistrierung zu ist, legst du Konten mit dem mitgelieferten Werkzeug an. Achte auf die Reihenfolge der Argumente – --pass steht vorn, sonst zeigt das Skript nur seine Hilfe:

docker compose exec app bin/manage_users --pass DEIN_PASSWORT --add DEINE@MAILADRESSE

Using password from commandline...
Created user with email DEINE@MAILADRESSE

Dass es geklappt hat, bestätigt der Status-Endpunkt:

curl -s https://DEINE_DOMAIN/status | grep -o '"registeredUsers":[0-9]*'

"registeredUsers":1

Auf der Startseite gibt es jetzt nur noch Sign In – keinen Registrieren-Knopf:

Schritt 5: Die erste Notiz

Nach dem Anmelden legst du mit New eine Notiz an. Links tippst du Markdown, rechts steht sofort das Ergebnis:

Tabellen, Aufgabenlisten mit anklickbaren Kästchen, Zitate, Codeblöcke, MathJax und ein Präsentationsmodus sind eingebaut. Wer die Notiz gleichzeitig offen hat, sieht deine Änderungen sofort – oben rechts steht, wie viele Leute gerade dabei sind.

Schritt 6: Fünf Stufen, wer was darf

Oben rechts über der Vorschau steht die aktuelle Berechtigung der Notiz. Ein Klick öffnet die Auswahl:

Die Stufen von offen nach zu:

• Editable – angemeldete Nutzer dürfen bearbeiten, Gäste dürfen lesen
• Limited – angemeldete Nutzer dürfen bearbeiten, Gäste bleiben ganz draußen
• Locked – nur der Besitzer bearbeitet, Gäste dürfen lesen
• Protected – nur der Besitzer bearbeitet, Gäste bleiben draußen
• Private – nur der Besitzer sieht die Notiz überhaupt

Eine sechste Stufe, Freely („Anyone can edit“), bietet HedgeDoc nur an, wenn Gäste mitschreiben dürfen. Mit CMD_ALLOW_ANONYMOUS: "false" fehlt sie im Menü.

Der Zusatz „forbid guests" ist der Punkt, an dem man sich vertut. Eine Notiz auf Limited ist für Außenstehende auch dann unsichtbar, wenn du sie veröffentlichst – der Aufruf endet mit einer Weiterleitung. Willst du jemandem ohne Konto etwas zu lesen geben, ist Locked die richtige Stufe. Der Unterschied ist eindeutig: Dieselbe veröffentlichte Notiz liefert einem Gast mit Limited eine 302 und mit Locked eine 200.

Schritt 7: Weitergeben

Über Publish bekommt die Notiz eine zweite, aufgeräumte Adresse unter /s/… – ohne Editor, ohne Werkzeugleiste, nur der fertige Text. Das ist die Fassung, die du verschickst:

Der Editor bleibt unter der ursprünglichen Adresse erreichbar; die veröffentlichte Fassung zieht bei jeder Änderung nach. Wer die Notiz nur lesen können soll, bekommt den /s/-Link und die Notiz steht auf Locked.

Wenn es nicht funktioniert

Dein Problem ist nicht dabei? Alle Fehlermeldungen durchsuchen →

Wartung & Backups

Updates laufen über den Image-Tag. HedgeDoc 1.x veröffentlicht alle paar Wochen eine Minor-Version; die Datenbankmigration passiert beim Start:

cd /opt/hedgedoc
docker compose exec -T database pg_dump -U hedgedoc hedgedoc > vor-update-$(date +%F).sql
sed -i 's/hedgedoc:1.12.0/hedgedoc:NEUE_VERSION/' compose.yaml
docker compose pull && docker compose up -d
docker compose logs app --tail 10

Der Dump davor ist keine Förmlichkeit – er ist der einzige Weg zurück, wenn eine Migration schiefgeht. Die Hauptversion von PostgreSQL fasst du dabei nicht mit an. Ein Sprung von 18 auf 19 braucht immer Dump und Import; ein bloßes Hochsetzen des Image-Tags endet damit, dass der Container mit einer Versionsmeldung stehen bleibt.

Sichern musst du drei Dinge:

pg_dump-Ausgabe          # Notizen, Konten, Berechtigungen
/opt/hedgedoc/uploads/   # hochgeladene Bilder
/opt/hedgedoc/.env       # Datenbankpasswort und Session-Secret

Das .env gehört ausdrücklich dazu: Ohne das CMD_SESSION_SECRET sind nach einer Wiederherstellung alle Sitzungen ungültig, ohne das Datenbankpasswort kommt die Anwendung nicht an ihre eigenen Daten. Ein täglicher Dump per systemd-Timer und beides zusammen ins Restic-Backup – mehr braucht es nicht.

Realistischer Aufwand: wenig. Ein Update pro Quartal, ein Blick auf die Notizliste, wenn du merkst, dass niemand mehr aufräumt. Der Punkt, den du dir im Kalender notieren solltest, ist die Postgres-Hauptversion: Solange du beim gepinnten Tag bleibst, passiert nichts – aber irgendwann läuft der Support aus, und dann ist Dump-und-Import fällig.