Wer seine Notizen, Recherchen und Wissensdatenbank wirklich unter eigener Kontrolle behalten möchte, kommt an SiYuan (思源笔记) kaum vorbei. Das unter AGPL-3.0 veröffentlichte Personal Knowledge Management System verbindet einen echten block-basierten Editor mit über 20 Blockelement-Typen, bidirektionalen Verlinkungen, Datenbank-Blöcken mit Relationen und Rollups sowie Karteikarten nach dem FSRS-Spaced-Repetition-Algorithmus – alles ohne Pflicht-Cloud, ohne Telemetrie und ohne monatliche Abo-Kosten. Mit über 44.000 GitHub-Stars und regelmäßigen Releases (aktuell v3.6.5, April 2026) ist es eines der aktivsten PKM-Projekte im Self-Hosting-Bereich. Dieser Artikel richtet sich an KMU-Admins, Entwickler und ambitionierte Selfhoster, die SiYuan als persönlichen Wissens-Server auf einem Linux-Host oder NAS mit Docker Compose betreiben wollen.

Voraussetzungen

Docker Engine ≥ 20.10 und das Docker Compose Plugin v2 (docker compose-Syntax) auf einem Linux-Host (Ubuntu 22.04+, Debian 12+ oder beliebige Docker-fähige Plattform). Falls du Docker noch nicht installiert hast, folge der Docker- und Compose-Grundlage.
Mindestens 512 MB freier RAM für den Container; empfohlen 1 GB+ bei umfangreichen Notizbüchern.
Ein persistentes Verzeichnis auf dem Host für den Workspace (empfohlen: mindestens 1 GB, je nach Notizumfang).
curl für die Schritt-Verifikation.
Optional: ein Reverse Proxy (nginx, Traefik oder Caddy) mit TLS-Zertifikat für den öffentlichen Zugriff. Ohne HTTPS werden Passwörter und Notizen unverschlüsselt übertragen.

Schritt 1: Projektordner anlegen

Lege einen dedizierten Ordner für den SiYuan-Stack an. Alle weiteren Dateien werden dort abgelegt.

mkdir -p /opt/siyuan
cd /opt/siyuan

Das Workspace-Verzeichnis, das später in den Container gemountet wird, muss vor dem ersten Start mit dem richtigen Besitzer angelegt werden. Überprüfe zunächst deine eigene UID und GID auf dem Host:

id $USER
# Ausgabe-Beispiel: uid=1000(ubuntu) gid=1000(ubuntu) groups=…

Dann das Workspace-Verzeichnis anlegen und den Besitzer setzen – hier für den Standardfall UID/GID 1000:

mkdir -p /opt/siyuan/workspace
chown -R 1000:1000 /opt/siyuan/workspace

Wenn dein Host-User eine abweichende UID hat (z. B. 1001), passe den chown-Befehl und später die .env-Werte entsprechend an.

Verifizieren: ls -la /opt/siyuan/ – das Verzeichnis workspace/ muss deinem Host-User gehören (Spalten „Besitzer" und „Gruppe" zeigen UID/GID 1000 oder deinen Benutzernamen).

Schritt 2: .env-Datei mit Zugangsdaten anlegen

Die .env-Datei hält alle Secrets und umgebungsspezifischen Werte aus der compose.yaml heraus. Erstelle sie im Projektordner:

# /opt/siyuan/.env

# Zugriffsschutz – PFLICHT: starkes Passwort wählen!
SIYUAN_ACCESS_AUTH_CODE=MeinSicheresPasswort2026!

# Host-User, unter dem der Container-Prozess laufen soll
PUID=1000
PGID=1000

# Zeitzone
TZ=Europe/Berlin

# Port auf dem Host (Standard: 6806)
SIYUAN_PORT=6806

# Workspace-Verzeichnis auf dem Host
SIYUAN_WORKSPACE_HOST=/opt/siyuan/workspace

Setze restriktive Dateiberechtigungen, damit der Auth-Code nicht für andere Nutzer lesbar ist:

chmod 600 /opt/siyuan/.env

Wichtig: Ohne einen gesetzten SIYUAN_ACCESS_AUTH_CODE kann jeder, der Port 6806 erreicht, sämtliche Notizen lesen und verändern. Wähle ein starkes, einzigartiges Passwort.

Verifizieren: cat /opt/siyuan/.env – alle Variablen müssen gesetzt sein. ls -la /opt/siyuan/.env zeigt Berechtigungen -rw-------.

Schritt 3: compose.yaml anlegen

Erstelle die compose.yaml im Projektordner. Für den Produktivbetrieb empfiehlt sich ein gepinnter Image-Tag (z. B. v3.6.5) statt :latest, damit automatische Updates keine Breaking Changes einspielen. In dieser Anleitung wird :latest verwendet, das zum Zeitpunkt der Erstellung auf dieselbe Version zeigt.

services:
  siyuan:
    image: b3log/siyuan:latest
    container_name: siyuan
    restart: unless-stopped
    ports:
      - "${SIYUAN_PORT:-6806}:6806"
    volumes:
      - ${SIYUAN_WORKSPACE_HOST:-/opt/siyuan/workspace}:/siyuan/workspace
    environment:
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      - TZ=${TZ:-Europe/Berlin}
      - SIYUAN_ACCESS_AUTH_CODE=${SIYUAN_ACCESS_AUTH_CODE}
    command:
      - "--workspace=/siyuan/workspace/"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6806"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

Ein paar Hinweise zur Konfiguration: Der command-Parameter --workspace hat immer Vorrang vor der gleichnamigen Umgebungsvariable. Das interne Programmverzeichnis /opt/siyuan/ im Container wird absichtlich nicht gemountet – nur der Workspace unter /siyuan/workspace ist relevant. Das healthcheck-Feld sorgt dafür, dass docker compose ps den tatsächlichen Zustand des Dienstes meldet.

Verifizieren: docker compose config im Projektordner ausführen – Docker gibt die aufgelöste Konfiguration ohne Fehler aus.

Schritt 4: Container starten

Starte SiYuan im Hintergrund:

docker compose up -d

Beim ersten Start lädt Docker das Image herunter (ca. 62 MB). Danach initialisiert SiYuan den Workspace – das dauert einige Sekunden.

Status prüfen:

docker compose ps

Erwartete Ausgabe (nach ca. 20 Sekunden):

NAME      IMAGE                  SERVICE   STATUS
siyuan    b3log/siyuan:latest    siyuan    Up (healthy)

Logs auf Fehler prüfen:

docker compose logs siyuan

Ein sauberer Start zeigt Zeilen wie kernel boot, workspace [/siyuan/workspace/] und listening on :6806 – keine permission denied- oder Port-Konflikt-Fehler.

Verifizieren:

curl -I http://localhost:6806
# Erwartete Ausgabe: HTTP/1.1 200 OK

Schritt 5: Ersteinrichtung im Browser

Öffne http://<HOST-IP>:6806 in einem modernen Browser. SiYuan präsentiert zunächst die Eingabemaske für den Autorisierungscode.

Gib den in der .env gesetzten SIYUAN_ACCESS_AUTH_CODE ein und bestätige.
Nach erfolgreichem Login erscheint der SiYuan-Workspace. Beim ersten Aufruf ist er leer – lege dein erstes Notizbuch über „Notizbuch erstellen" an.
Erkunde die Kernfunktionen: Blöcke per /-Befehl einfügen, bidirektionale Links mit [[ anlegen, Datenbank-Blöcke für strukturierte Inhalte nutzen.

Eigenschaft	Wert
Docker-Image	b3log/siyuan:latest (Docker Hub)
Aktuelle stabile Version	v3.6.5 (April 2026)
Image-Größe	ca. 62 MB
Architekturen	linux/amd64, linux/arm64
Port	6806 (Web-UI, REST-API, WebSocket /ws)
Datenbank	Eingebettetes SQLite – kein externer DB-Dienst nötig
Lizenz	AGPL-3.0
Workspace-Pfad (Container)	/siyuan/workspace

Verifizieren: Im Browser erscheint nach der Anmeldung der SiYuan-Editor-Workspace ohne Fehlermeldungen. Lege testweise einen Block an und lade die Seite neu – der Inhalt muss erhalten bleiben. Prüfe parallel auf der Kommandozeile: ls -la /opt/siyuan/workspace/ – SiYuan hat Unterverzeichnisse wie conf/ angelegt.

Schritt 6: Reverse Proxy und HTTPS einrichten (empfohlen)

Ohne HTTPS überträgt SiYuan Passwort und Notizen im Klartext. Für den Betrieb im lokalen Netz ohne eigene Domain reicht HTTP über Port 6806; sobald der Dienst von außen erreichbar sein soll, ist ein Reverse Proxy mit TLS-Terminierung Pflicht. Eine vollständige Caddy-Anleitung findest du unter Caddy als Reverse Proxy mit automatischem HTTPS; für nginx-basierte Setups hilft die nginx-Reverse-Proxy-Anleitung.

Beim nginx-Einsatz muss der /ws-WebSocket-Endpunkt explizit weitergeleitet werden, sonst laden Seiten zwar, aber Live-Updates funktionieren nicht:

location / {
    proxy_pass http://siyuan:6806;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

location /ws {
    proxy_pass http://siyuan:6806;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Wichtig: Kein URL-Rewriting verwenden (also kein /siyuan/ auf / umschreiben). SiYuan verträgt keine Pfad-Umschreibungen und reagiert mit Authentifizierungs-Fehlerschleifen. Am sichersten ist eine eigene Sub-Domain (notes.example.com), die direkt auf Port 6806 zeigt.

Verifizieren: Nach dem Reverse-Proxy-Setup: curl -I https://notes.example.com gibt HTTP/2 200 zurück. Im Browser erscheint kein Zertifikats-Warning, und der WebSocket-Status in den Browser-Entwicklerwerkzeugen (Netzwerk-Tab → WS) zeigt eine aktive Verbindung zu /ws.

Schritt 7: Updates und Backup

SiYuan hat zwar eine eingebaute Update-Funktion in der UI, im Docker-Betrieb sollte das Update jedoch immer über das Image erfolgen – nicht über den UI-Updater:

cd /opt/siyuan
docker compose pull
docker compose up -d

SiYuan ist kurze Zeit nicht erreichbar, während der neue Container hochfährt. Für Produktionsumgebungen: Vor dem Update den Image-Tag in der compose.yaml auf einen spezifischen Tag (z. B. b3log/siyuan:v3.6.5) pinnen und erst nach eigenem Test auf die neue Version heben. Welche Tools dabei helfen, neue Image-Tags zu erkennen, zeigt die Anleitung zu Docker-Container-Updates mit Diun und WUD.

Das Backup ist denkbar einfach: Alle Daten – Notizbücher, Anhänge, Konfiguration und die SQLite-Datenbank – liegen ausschließlich unter /opt/siyuan/workspace/. Eine regelmäßige Sicherung dieses Verzeichnisses ist ausreichend. Für automatisierte, verschlüsselte Off-Site-Backups empfiehlt sich Restic mit automatisierter cron-Ausführung.

Container bei Bedarf stoppen:

docker compose down

Verifizieren: Nach dem Update: docker compose ps zeigt Status Up (healthy), docker compose logs siyuan | head -20 zeigt die neue Versionszeile ohne Fehler. Nach dem Backup: ls -lh /opt/siyuan/workspace/data/ – alle Notizbücher sind vorhanden.

Troubleshooting / Typische Fehler

permission denied beim Containerstart: Das häufigste Problem. Ursache: /opt/siyuan/workspace gehört root oder einem anderen Nutzer. Fix: chown -R 1000:1000 /opt/siyuan/workspace (mit der tatsächlichen UID/GID deines Host-Users). Anschließend docker compose down && docker compose up -d.
Auth-Code-Eingabe erscheint nicht / Seite bleibt leer: Prüfe, ob der Container tatsächlich läuft: docker compose ps und docker compose logs siyuan. Läuft er, aber die Seite ist leer, deutet es oft auf einen Proxy mit URL-Rewriting hin.
WebSocket-Verbindung bricht ab (Echtzeit-Updates fehlen): nginx ohne proxy_set_header Upgrade-Block für /ws. Ergänze den WebSocket-Abschnitt wie in Schritt 6 beschrieben und lade die nginx-Konfiguration neu (nginx -s reload).
PUID/PGID stimmt nicht mit Host-User überein: Wenn nachträglich Dateien im Workspace entstehen, die einem anderen Nutzer gehören, prüfe mit id $USER die tatsächliche UID und setze PUID und PGID in der .env entsprechend. Danach docker compose up -d.
Desktop- oder Mobile-App verbindet sich nicht: Das ist kein Fehler, sondern eine Einschränkung. Docker-Instanzen von SiYuan unterstützen keine Verbindung durch die native Desktop- oder Mobile-App. Zugriff ist ausschließlich per Browser möglich.
Export (PDF, HTML, Word) fehlt: Diese Export-Funktionen sind im Browser-Modus (Docker) nicht verfügbar – sie erfordern die Desktop-App. Markdown-Export funktioniert hingegen auch im Browser.
Port 6806 bereits belegt: Ändere in der .env den Wert von SIYUAN_PORT auf einen freien Port (z. B. 6807) und starte den Container neu.

Häufige Fragen

Kann ich SiYuan mit meiner Desktop-App verbinden?

Nein. Die Docker-Instanz ist rein browser-basiert. Die nativen Desktop- und Mobile-Apps von SiYuan kommunizieren nicht mit einem selbst gehosteten Docker-Server. Wer Geräte synchronisieren möchte, hat zwei Optionen: das kostenpflichtige SiYuan Cloud Sync oder ein gemeinsam gemountetes Verzeichnis (z. B. per WebDAV oder Syncthing).

Brauche ich PostgreSQL oder Redis?

Nein. SiYuan verwendet eine eingebettete SQLite-Datenbank. Es ist kein externer Datenbankdienst erforderlich – das macht das Setup besonders schlank und wartungsarm.

Wie setze ich den Auth-Code zurück, wenn ich ihn vergessen habe?

Öffne die .env-Datei, trage einen neuen Wert für SIYUAN_ACCESS_AUTH_CODE ein und führe docker compose up -d aus. Der Container liest die Variable beim Neustart und akzeptiert ab sofort den neuen Code. Alternativ kannst du in der Datei /opt/siyuan/workspace/conf/conf.json das Feld accessAuthCode direkt anpassen, wenn der Container gestoppt ist.

Was ist mit Ende-zu-Ende-verschlüsselter Sync?

SiYuan bietet optionale E2E-verschlüsselte Synchronisierung über den SiYuan Cloud Sync-Dienst – das ist ein kostenpflichtiges Add-on und hat nichts mit der lokalen Docker-Instanz zu tun. Die Docker-Instanz selbst ist vollständig kostenlos und unbegrenzt nutzbar; alle Daten bleiben lokal.

Wie sichere ich die Instanz über den Auth-Code hinaus ab?

Pflicht ist ein starker SIYUAN_ACCESS_AUTH_CODE. Empfohlen ist ein Reverse Proxy mit HTTPS. Optional lässt sich eine zusätzliche Authentifizierungsschicht vorschalten, etwa mit Authentik oder Authelia als SSO-Layer. Port 6806 sollte niemals direkt ohne Auth ans öffentliche Internet exponiert werden.

Fazit

SiYuan ist eine der überzeugendsten Privacy-first-PKM-Lösungen im Self-Hosting-Bereich: kein externer Datenbankdienst, ein einziges 62 MB großes Docker-Image, ein echter block-basierter Editor mit bidirektionalen Links und eine solide Zugriffssicherung per Auth-Code. Der Docker-Betrieb ist in unter 10 Minuten erledigt, wenn das Workspace-Verzeichnis mit den richtigen Berechtigungen angelegt wird – das ist der einzige Stolperstein, der regelmäßig zu Problemen führt. Wer die Desktop-App-Features (PDF-Export, Markdown-Import) benötigt, wird im reinen Browser-Modus eingeschränkt sein; als server-seitiger Wissens-Hub für den Browser-Zugriff ist SiYuan jedoch kaum zu schlagen.

Weiterführende Anleitungen und Quellen

Offizielle Quellen: SiYuan GitHub Repository (README, Changelog, Issues) und SiYuan auf Docker Hub (Image-Tags, Multi-Arch-Details).