SiYuan Deployment Guide Docker Compose

Overview

SiYuan (思源笔记) is a privacy-first, self-hosted, fully open-source personal knowledge management system with block-level referencing and Markdown WYSIWYG editing. This guide walks through deploying it on a Linux server using Docker Compose.

Architecture

• SiYuan — The knowledge management application (listens on port 6806)
• Workspace Volume — Persistent data storage (mounted from host)

SiYuan is a single-container deployment with no external database or cache dependencies — all data is stored as files in the workspace directory, making it exceptionally simple to deploy and back up.

Prerequisites

• Assumes that you have a Linux server with Docker (24+) and Docker Compose v2+ installed
• Port 6806 open in your firewall (or use a reverse proxy for domain-based access)
• SSH access to the server

Step 1: Prepare the Server

# SSH into your server
ssh root@your-server-ip

# Create the deployment directory
mkdir -p /home/siyuan/workspace
cd /home/siyuan

Step 2: Create docker-compose.yml

Create /home/siyuan/docker-compose.yml:

version: "3.9"
services:
  main:
    image: b3log/siyuan
    command: ["--workspace=/siyuan/workspace/", "--accessAuthCode=${AuthCode}"]
    ports:
    - 6806:6806
    volumes:
    - /home/siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
    - TZ=${TZ}
    - PUID=${PUID}
    - PGID=${PGID}

The .env file should look like the following

AuthCode=ReplacewithYourPassword
TZ=Asia/Singapore
PUID=1000
PGID=1000

Parameter	Description
--workspace	Path inside the container where data is stored. Must match the volume mount.
--accessAuthCode	Access authorization code — always change this! Without it, anyone can access your data.
PUID / PGID	User and group IDs for file permissions. Match these to a user on your host system to avoid permission issues when accessing mounted files.
TZ	Time zone for log timestamps. See tz database for valid values.

Step 3: Set Ownership (Optional)

Ensure the workspace directory is owned by the user matching your PUID/PGID:

chown -R 1000:1000 /home/siyuan/workspace

Step 4: Deploy

cd /home/siyuan

# Start SiYuan
docker compose up -d

# Check container status
docker compose ps

# View logs to confirm startup
docker compose logs siyuan

You should see log output ending with:

I 2026/06/02 10:14:24 serve.go:231: kernel [pid=1] http server [0.0.0.0:6806] is booting
I 2026/06/02 10:14:24 working.go:216: kernel booted

Step 5: Verify Deployment

# Check if the container is running
docker ps --filter name=siyuan --format "{{.ID}} {{.Status}}"

# Test locally on the server
curl -s -o /dev/null -w "HTTP %{http_code}" http://localhost:6806/

# Check the login page (should return HTML)
curl -s -A "Mozilla/5.0" -L http://localhost:6806/ | head -20

Expected: HTTP 302 (redirects to /check-auth) or HTTP 200 with HTML content showing the login page.

Step 6: Access the Web Interface

1. Open your browser to http://your-server-ip:6806
2. You will be redirected to the Access Authorization login page
3. Enter the accessAuthCode you configured (e.g., YourStrongAuthCodeHere!)
4. Once authenticated, you can start creating notes, notebooks, and organizing your knowledge

Known Limitations (Docker deployment)

• Does not support desktop and mobile application connections — only use via browser
• Export to PDF, HTML, and Word formats is not supported in Docker mode
• Importing Markdown files is not supported
• If you need these features, use the desktop application instead

Production Hardening Checklist

• [ ] Use a strong, unique accessAuthCode (not a dictionary word)
• [ ] Set up Nginx (or another reverse proxy) with HTTPS (Let’s Encrypt via Certbot)
• [ ] Configure WebSocket reverse proxy for /ws path when using Nginx
• [ ] Do NOT use URL rewriting for redirection — it may break authentication
• [ ] Set up regular backups of the workspace directory (/home/siyuan/workspace)
• [ ] Keep the Docker image updated: docker compose pull && docker compose up -d
• [ ] Monitor logs: docker compose logs --tail=50 -f
• [ ] Consider using a non-root user for PUID/PGID (1000:1000 is the default)
• Upgrading
• cd /home/siyuan<br>docker compose pull<br>docker compose up -d
• SiYuan data is stored entirely in the workspace directory, so upgrades are safe and non-destructive.
• Test Deployment Reference
• This guide was verified against SiYuan v3.6.5 on a DigitalOcean server running Ubuntu 24.04 with Docker 29.5.2 and Docker Compose v5.1.4.
• Troubleshooting
• Container keeps restarting
• Check the logs: docker logs siyuan. If you see errors about /home/siyuan/ not found, ensure you are using the default PUID=1000/PGID=1000 (the container expects these to create the siyuan user’s home directory).
• Permission issues with mounted volumes
• Ensure the workspace directory on your host has the same ownership as your PUID/PGID values:
• chown -R 1000:1000 /home/siyuan/workspace
• Cannot access from browser
• Check your firewall rules:
• # Check if port 6806 is open<br>ufw status<br># If ufw is enabled, allow the port<br>ufw allow 6806<br><br># Or check cloud firewall / security group settings on your hosting provider
• Resources
  • GitHub Repository
  • Docker Hub Image
  • Official Documentation