SiYuan: a self-hosted, block-level notes app with a Go kernel and a TypeScript front end

The problem SiYuan solves, and who it is actually for

Most note apps organise content into files and folders. SiYuan organises it into blocks, and the README puts block-level reference and two-way links first in its feature list. That ordering is the point. A paragraph, a list item or a table cell can be referenced from somewhere else and edited in place, so a note is a graph of addressable fragments rather than a tree of documents. If you have ever copied a paragraph into a second note and then had to remember to update both, this is the problem being solved.

The audience is narrower than the feature list suggests. SiYuan is aimed at people who want to keep their knowledge base on hardware they control. The README calls it privacy-first and self-hosted, and the download section offers installation packages, package managers, Docker, Unraid and TrueNAS. That is a server-shaped distribution, not a consumer app store listing. It also ships Android, iOS and HarmonyOS clients, plus a Chrome/Edge extension for web clipping.

A second audience is developers. The repository exposes an API documented in docs/API.md, a plugin API in a separate project called petal, and JavaScript/CSS snippets inside the app. If you want to script your notes rather than just write in them, the surface exists. The cost is that you are now maintaining a service.

How the kernel, the editor engine and the data repo fit together

The repository splits into app/ and kernel/. The Dockerfile builds them in two stages: a node:22 stage that runs pnpm install and pnpm run build inside app/, and a golang:1.26-alpine stage that compiles kernel/ with the build tags fts5 and sqlcipher. The final image is alpine:latest, copies the kernel binary and entrypoint.sh into /opt/siyuan/, and exposes port 6806.

Those two build tags tell you more about the design than the feature list does. fts5 is SQLite full-text search, so search runs inside the database rather than against an external index. sqlcipher is the encrypted SQLite variant, which is how the local store is protected. Both are compile-time choices, not runtime options, so a self-built kernel without those tags behaves differently from the released one.

The editor is not part of this repository. The README's architecture table lists lute as the editor engine and dejavu as the data repo, both separate projects. Spaced repetition lives in riff, and the community marketplace is bazaar. That means a bug in rendering or in sync history may belong to a different repository than the one you filed against, and the release cadence of those projects is not the same as the kernel's. The API is documented in docs/API.md, which is the entry point if you want to talk to the kernel directly rather than through the UI.

Installing SiYuan with Docker and taking the first note

The README recommends installing through an application market on desktop and mobile so that upgrades are one click. For a server, it states that the easiest way is Docker, with the image name b3log/siyuan. The Dockerfile sets RUN_IN_CONTAINER=true and TZ=Asia/Shanghai as environment defaults, and the entrypoint runs the kernel with the serve subcommand.

The Dockerfile declares its port with EXPOSE and sets the working directory to /opt/siyuan/. The command it ships as the default is the kernel binary followed by serve, which is written in the Dockerfile as a JSON array. The README does not give a docker run example in the excerpt available here, so the command below is the Dockerfile's own CMD rather than a publishing recipe:

ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]
CMD ["/opt/siyuan/kernel", "serve"]

One detail in the Dockerfile deserves attention before you copy any tutorial from elsewhere. The comment above CMD states that the default command starts the server, and that if you pass extra arguments through docker run or a compose command: field, you must include the serve subcommand yourself, because your arguments replace CMD entirely. Dropping serve produces a container that starts and does nothing useful.

The README's file structure section says the program sits under /opt/siyuan/. The README does not document a login or access step in the excerpt available here, and it does not spell out an authentication header for the API in docs/API.md, so read that file before wiring a script to the kernel.

Where SiYuan is the wrong tool

The release history is the first warning. The most recent releases listed are v3.8.2-beta.4, v3.8.2-beta.3 and v3.8.2-beta.2, all pushed on 2026-08-29. A project whose visible output is a run of betas is telling you something about its stability expectations. If your workflow cannot tolerate a regression in the editor or the sync layer, pin a version and read CHANGELOG.md before moving.

The second warning is the data repo key. The README's FAQ includes a question about what to do if the data repo key is lost. That phrasing implies the key is not trivially recoverable, and it is not something the README documents a rollback for. Treat it as a credential you back up separately from the notes.

Third, self-hosting means you own availability. The README also asks whether SiYuan supports data synchronisation through a third-party sync disk, which is a question people ask precisely because they want to avoid running the sync service themselves. If you want someone else to be responsible for uptime and conflict resolution, a hosted product is a better fit, and no amount of Docker configuration changes that.

Finally, the licence. AGPL-3.0 is a strong copyleft licence with a network clause. If you plan to expose a modified SiYuan to other users over a network, the obligations are different from those of a permissive licence. That is a reason to read LICENSE and THIRD_PARTY_NOTICES.md rather than a reason to avoid the project, but it is a real consideration for anyone embedding it in a product.

SiYuan against Obsidian: blocks versus files

The comparison people search for is SiYuan versus Obsidian, and the difference is structural rather than cosmetic. Obsidian's unit is a Markdown file in a vault you can open in any text editor. SiYuan's unit is a block stored in an encrypted SQLite database, with Markdown WYSIWYG as the editing surface rather than the storage format. The README does list standard Markdown with assets as an export option, so you are not locked in permanently, but the live store is not a folder of .md files.

That changes what you can do. Block-level reference and two-way links work because every block has an identity the kernel can resolve. In a file-based tool, linking to a heading is the closest equivalent, and it breaks when the heading text changes. The trade is portability and inspectability: a vault of plain files is readable by grep, by git and by any editor, while SiYuan's store is read through the application or its API.

A second difference is the deployment model. SiYuan is designed to run as a server with a browser client, which is why Docker, Unraid and TrueNAS appear in the download section. Obsidian is a local application. If your requirement is a notes service reachable from any device you own, SiYuan's architecture is aimed at that. If your requirement is a folder you can sync with whatever tool you already use, the file-based model is simpler.

Note that some SiYuan features are reserved for paid members. The README says most features are free, even for commercial use, and points to a pricing page for the rest. Check that page against your own feature list before assuming the free tier covers your use.

Maintenance, upgrades and what the licence asks of you

The repository is not archived, and the last push was on 2026-08-29. That is recent enough that the project is clearly being worked on, but the releases at that date are betas. Plan upgrades around CHANGELOG.md rather than around a version number, and if you run the Docker image, treat a tag change as a deployment you test rather than one you apply to a live instance.

The upgrade path depends on how you installed it. The README states that installing through the application market on desktop and mobile lets you upgrade with one click. A Docker deployment does not have that convenience: you pull a new image and restart, and the kernel's migration behaviour on an existing workspace is not described in the excerpt available here. That is a gap worth closing by testing against a copy of your workspace before you touch the real one.

On licensing, AGPL-3.0 governs the code in this repository. The README carries an AGPLv3 badge, and the Dockerfile copies LICENSE and THIRD_PARTY_NOTICES.md into the image, so the notices travel with the artifact. If you modify the kernel and let other people use it over a network, the network clause is the part to read carefully. This is not legal advice, and the specific obligations depend on what you distribute and how, so take the licence text and THIRD_PARTY_NOTICES.md to someone qualified if the answer matters to your business.

The practical maintenance cost is the Go kernel plus its dependencies. The Dockerfile installs gcc and musl-dev and sets CGO_ENABLED=1, which means the build is not a pure static Go compile; it links against C libraries for the SQLite extensions. Building it yourself is possible, and the Dockerfile is a working recipe, but you inherit the responsibility for rebuilding when those libraries move.

Editorial conclusion

Adopt SiYuan if you want block-level references, Markdown WYSIWYG and a server you control, and you are comfortable running a project whose releases are still landing as betas. Do not adopt it if you need a stable plugin API contract or cannot operate a Go binary behind your own reverse proxy. Before committing a real notebook, verify three things: that the Docker image starts and answers on port 6806, that your sync or backup strategy accounts for the data repo key the FAQ warns about, and that the licence terms of AGPL-3.0 suit how you intend to distribute anything you build on top of it.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes