SiYuan

Last reviewed Aug 26, 2026 · 894 words

The Docker image is not a sync server, and misunderstanding that costs most new SiYuan self-hosters their first weekend. Every SiYuan installation, whether the desktop app, the phone app, or the container on port 6806, is a complete local kernel with its own workspace on its own disk. Devices stay in step by each syncing to a shared storage target, encrypted end-to-end, not by talking to your server. So "self-hosting SiYuan" really means two things: running the container to get browser access from any machine, and pointing every kernel at an S3 bucket or WebDAV folder you control. Do both and you have a Notion replacement with block references, offline operation, and data that never leaves hardware you own.

What the container actually gives you

The b3log/siyuan image runs the same kernel as the desktop app, serving the full editor to a browser. That is useful on a work laptop where you cannot install software, or as the always-on instance that a sync schedule can rely on. The run command is short:

services:
  siyuan:
    image: b3log/siyuan:latest
    command: ["--workspace=/siyuan/workspace/", "--accessAuthCode=change-this-passphrase"]
    ports:
      - "6806:6806"
    volumes:
      - ./workspace:/siyuan/workspace
    user: "1000:1000"
    restart: unless-stopped

--accessAuthCode is the only thing standing between the internet and your notes; there is no user system, just this one passphrase. Never publish port 6806 without it, and put the whole thing behind Tailscale or a reverse proxy with TLS, because the passphrase travels in the clear over HTTP. The user: line should match the owner of ./workspace on the host, or the kernel starts and immediately fails to write.

Sync goes through a bucket, not through your server

Open Settings, Cloud, and pick the S3 or WebDAV provider. Every device with the same target and the same encryption passphrase becomes part of the sync group; the container is just one more member. A MinIO bucket on the same box, a Nextcloud WebDAV folder, or any S3-compatible object store all work. Data is encrypted client-side before upload, so the storage provider sees only ciphertext, and the passphrase is never recoverable if lost. Write it in your password manager the moment you set it. The official SiYuan Cloud subscription is the same mechanism with their storage attached; you are replacing the storage, not the feature.

The one discipline sync demands is closing the editor, or at least letting the automatic sync finish, before switching devices. SiYuan resolves conflicts by keeping both versions and logging it, which is safe but tedious to clean up after a week of ping-ponging between a phone and a desktop.

The block model is why you would pick it over Trilium or Logseq

Every paragraph, heading, list item, and table row is a block with a stable ID, and any block can be referenced or embedded anywhere else with a bidirectional backlink. That is a deeper granularity than Trilium, which links at the note level, and closer to Logseq's outliner, except SiYuan is document-shaped rather than outline-shaped. If your notes are long-form documents you want to cross-reference paragraph by paragraph, SiYuan fits; if you think in nested bullets, Logseq feels more natural. My notes apps you own piece runs through the wider field and where each one stops being fun.

Your data is JSON, and export is your exit

The workspace stores each document as a .sy file, which is JSON describing the block tree, not Markdown. Grep works on the content, but you cannot open a .sy in a text editor and get a readable note, and the format is SiYuan's own. The escape hatch is the export menu: single documents, whole notebooks, or the entire workspace can be exported to Markdown with assets, and the result imports cleanly into most other tools. Do a full Markdown export once a quarter alongside your workspace backup. The workspace also keeps a data history (Settings, About, Data history) that snapshots changes and lets you roll a document back, which has saved me from a bad paste more than once.

The documentation gap is real

SiYuan is developed by a Chinese team, and the catalogue's note that documentation is strongest in Chinese is accurate. The English UI is complete and the in-app user guide is translated, but forum threads, plugin READMEs in the marketplace, and the most detailed troubleshooting tend to be in Chinese first. Machine translation gets you 90% of the way; the remaining 10% is why this sits at Medium difficulty rather than Easy. The project site and the GitHub issues are the two places to search before assuming a feature is missing.

What I'd do

Desktop app on the main machine, phone app for capture, the container above on a home server reachable only over Tailscale, and a MinIO bucket on that same server as the sync target for all three. Encryption passphrase and access code both in the password manager. Nightly backup of the MinIO bucket and the container workspace, quarterly Markdown export as the exit. Run it that way and SiYuan is the closest thing to Notion that works on a plane, and the notes category does not have many that can say the same.