Deploying SiYuan

Introduction

SiYuan is a privacy-first personal knowledge management system that combines the best features of note-taking apps, wikis, and outliner tools. Built with a local-first architecture, SiYuan stores all your data in plain files while offering powerful features like block-level editing, bidirectional linking, and end-to-end encrypted cloud sync.

Unlike traditional note-taking applications, SiYuan treats every piece of content as a block that can be referenced, embedded, and queried across your entire knowledge base. This block-based architecture enables powerful workflows for researchers, writers, developers, and knowledge workers.

Key features of SiYuan include:

Block-Based Editing: Every paragraph, heading, list, and code block is an individual block that can be referenced and embedded
Bidirectional Links: Create connections between notes with backlinks automatically tracked and displayed
Local-First Storage: All data stored locally in standard formats, ensuring you always have access to your notes
End-to-End Encryption: Optional cloud sync with full encryption, so only you can read your data
Graph View: Visualize connections between your notes in an interactive knowledge graph
Full-Text Search: Instantly find anything in your knowledge base with powerful search
SQL Query: Query your notes using SQL for advanced filtering and analysis
Templates and Snippets: Create reusable content blocks and templates
Math and Diagrams: Native support for LaTeX math, Mermaid diagrams, and code highlighting
PDF Annotation: Import and annotate PDF documents within SiYuan
Daily Notes: Built-in daily note functionality for journaling and quick capture
Plugin System: Extend functionality with community plugins
Open Source: Core features available under AGPL-3.0 license

This guide walks through deploying SiYuan on Klutch.sh using Docker, configuring persistent storage for your notes, and accessing your knowledge base from anywhere.

Why Deploy SiYuan on Klutch.sh

Deploying SiYuan on Klutch.sh provides several advantages for managing your personal knowledge:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds SiYuan without complex configuration. Push to GitHub and your knowledge base deploys automatically.

Persistent Storage: Attach persistent volumes for your workspace data. Your notes, assets, and configurations survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your knowledge base from any device.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your workspace size. Start small and scale as your knowledge base grows.

Environment Variable Management: Securely store access tokens and configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your SiYuan instance for easy, memorable access.

Always-On Availability: Access your knowledge base 24/7 from any device without managing your own server.

Prerequisites

Before deploying SiYuan on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your SiYuan configuration
Basic familiarity with Docker and containerization concepts
(Optional) A custom domain for your SiYuan instance

Deploying SiYuan on Klutch.sh

Create a GitHub Repository

Create a new GitHub repository to store your SiYuan deployment configuration.

Create Your Dockerfile

Create a Dockerfile in your repository:

FROM b3log/siyuan:latest

ENV SIYUAN_ACCESS_AUTH_CODE=${SIYUAN_ACCESS_AUTH_CODE}
ENV SIYUAN_WORKSPACE=/siyuan/workspace

EXPOSE 6806

ENTRYPOINT ["/opt/siyuan/kernel", "--workspace=/siyuan/workspace", "--accessAuthCode=${SIYUAN_ACCESS_AUTH_CODE}"]

Push Your Repository to GitHub

Commit and push your Dockerfile to your GitHub repository.

Generate an Access Code

Create a secure access code that will protect your SiYuan instance. This should be a strong, unique password.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project for your SiYuan deployment.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your SiYuan repository.

Configure Environment Variables

Add the following environment variable:

Variable	Value
`SIYUAN_ACCESS_AUTH_CODE`	Your secure access code

Configure HTTP Settings

Set the traffic type to HTTP and configure the internal port to 6806.

Attach Persistent Storage

Add persistent volumes for your data:

Mount Path	Recommended Size	Purpose
`/siyuan/workspace`	10 GB+	Your notes, assets, and workspace data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build your container and start SiYuan with your configuration.

Access SiYuan

Once deployment completes, access your SiYuan instance at your app’s URL. Enter your access code when prompted to authenticate.

Initial Setup

After accessing SiYuan for the first time:

Enter your access code to authenticate
Create or open a notebook to start taking notes
Explore the settings to customize your experience
Consider enabling cloud sync if you want encrypted backups

Working with SiYuan

SiYuan uses a block-based structure for organizing content:

Documents: Top-level containers for your notes
Blocks: Individual pieces of content (paragraphs, headings, lists, etc.)
References: Link blocks together using (( syntax
Embeds: Embed blocks in other documents using {{ syntax
Tags: Organize notes with hashtags

Additional Resources

Conclusion

Deploying SiYuan on Klutch.sh gives you a powerful, privacy-first knowledge management system accessible from anywhere. The combination of block-based editing, bidirectional links, and local-first storage makes SiYuan an excellent choice for building your personal knowledge base.

With Klutch.sh handling the infrastructure, you can focus on what matters most: capturing, connecting, and developing your ideas into a comprehensive second brain that grows with you over time.