SiYuan: A Privacy-First Personal Knowledge Management Software

This guide provides instructions for deploying and using SiYuan, a privacy-first, self-hosted, fully open-source personal knowledge management software.

1. Prerequisites

Before installing SiYuan, ensure you have the following:

• Operating System: Windows, macOS, Linux, Android, iOS, or HarmonyOS.
• Docker (for Docker deployment): Docker Engine installed and running.
• Unraid (for Unraid hosting): An Unraid OS installation.
• TrueNAS (for TrueNAS hosting): A TrueNAS installation.

2. Installation

SiYuan offers multiple installation methods depending on your platform and preference.

App Market

For desktop and mobile devices, SiYuan can be installed directly from various app markets:

• Windows: Microsoft Store (coming soon)
• macOS: Mac App Store (coming soon)
• Linux: Snap Store (coming soon)
• Android: Google Play (coming soon)
• iOS: Apple App Store (coming soon)
• HarmonyOS: Huawei AppGallery (coming soon)

Installation Package

Download the appropriate installation package for your operating system from the releases page:

• Windows: .exe installer
• macOS: .dmg or .zip archive
• Linux: .AppImage, .deb, .rpm packages

Follow the on-screen instructions for your chosen package.

Package Manager

SiYuan can be installed via package managers on some platforms:

• macOS (Homebrew):

  brew install --cask siyuan
  

• Linux (Snap):

  sudo snap install siyuan
  

Docker Hosting

To run SiYuan as a Docker container:

1. Pull the Docker image:

   docker pull b3log/siyuan
   

2. Run the container:

   docker run -d --name siyuan -p 6806:6806 -v /path/to/your/data:/siyuan/workspace b3log/siyuan
   

   • Replace /path/to/your/data with the desired host directory to store your SiYuan data.
   • The -p 6806:6806 maps the container's port 6806 (SiYuan's default port) to the host's port 6806.
3. Access SiYuan: Open your web browser and navigate to http://localhost:6806.

Unraid Hosting

For Unraid users, SiYuan can be deployed via the Docker template. Search for "SiYuan" in the Community Applications plugin and follow the setup instructions. Ensure you map a host path for the /siyuan/workspace volume.

TrueNAS Hosting

For TrueNAS users, SiYuan can be deployed as a Docker container within a TrueNAS jail or using the built-in Docker capabilities. Refer to TrueNAS documentation for specific steps on deploying Docker containers. Map a dataset for persistent storage to the /siyuan/workspace path within the container.

Insider Preview

For early access to new features, you can download Insider Preview builds from the releases page. These builds might be less stable.

3. Configuration

SiYuan primarily manages its configuration internally. However, for specific features or deployments, consider the following:

• Data Storage: SiYuan stores all data in a local directory (workspace). When using Docker, ensure the /siyuan/workspace volume is correctly mapped to a persistent host directory.
• API: SiYuan exposes an API. Refer to the API documentation for details on available endpoints and how to interact with them.
• AI Integration: For AI writing and Q/A chat, you will need to configure your OpenAI API key within the SiYuan application settings.
• Custom Snippets: SiYuan supports JavaScript/CSS snippets for customization. These can be managed within the application.

4. Build & Run (Local Development)

SiYuan is built with TypeScript and Go. To build and run from source:

1. Clone the repository:

   git clone https://github.com/siyuan-note/siyuan.git
   cd siyuan
   

2. Install dependencies:

   • For the TypeScript frontend:

     npm install # or yarn install
     

   • For the Go backend, ensure you have Go installed. Dependencies are typically managed by Go modules and will be fetched during the build process.

3. Build: The build process usually involves compiling the TypeScript frontend and the Go backend. Specific build commands are not explicitly provided in the README, but common commands for TypeScript projects include:

   npm run build # or yarn build
   

   For the Go backend, you would typically use:

   go build ./cmd/siyuan # (assuming the main package is in cmd/siyuan)
   

   Refer to the package.json scripts and Go build configurations within the repository for exact commands.

4. Run: After building, you would typically run the compiled executable or start the development server.

   • For development, there might be a command like:

     npm run dev # or yarn dev
     

   • For production, you would run the compiled backend executable and serve the frontend assets.

5. Deployment

SiYuan is designed for self-hosting. The primary deployment methods are:

• Desktop/Mobile Application: The most straightforward deployment is using the official installers or app store versions for your device.
• Docker Container: Recommended for server environments, NAS devices (Unraid, TrueNAS), or anyone preferring containerized applications.
  • Follow the "Docker Hosting" instructions in the Installation section. Ensure the Docker container is configured to start automatically on system boot.
• Manual Server Deployment: While not explicitly detailed, you could theoretically build SiYuan from source and run the compiled binaries on a server. This would involve:
  1. Building the frontend and backend as described in "Build & Run".
  2. Copying the compiled assets and executable to your server.
  3. Setting up a system service (e.g., systemd) to manage the SiYuan process.
  4. Configuring a reverse proxy (e.g., Nginx, Caddy) if you want to access it via a domain name with SSL.

6. Troubleshooting

• Data Repo Key Lost: If you lose your data repository key, you will not be able to decrypt your data. SiYuan emphasizes privacy and local control, so there's no central recovery mechanism. Always back up your data and keys securely.
• Upgrade Issues: If you encounter issues after upgrading, try the following:
  1. Backup your workspace before upgrading.
  2. Restart the application/container.
  3. Check the official discussion forum or GitHub issues for similar reports.
• Block Icons Missing: If some blocks (e.g., paragraph blocks in list items) cannot find their block icon, this might be a UI rendering issue. Try restarting the application. If the problem persists, report it on the official forum or GitHub.
• "Does it support data synchronization through a third-party sync disk?": Yes, SiYuan stores data in a local directory, which can be synchronized using third-party sync services like Dropbox, Google Drive, or Nextcloud. However, be aware of potential conflicts if multiple instances are editing the same data simultaneously.
• "How does SiYuan store data?": SiYuan stores all your data in a local directory called the "workspace." This workspace contains all your notes, assets, and configurations.
• "Is SiYuan open source?": Yes, SiYuan is fully open source under the AGPLv3 license.
• "Do I need to pay for it?": Most features are free, even for commercial use. Some advanced features are available to paid members. Refer to the Pricing page for details.