Skip to main content
Said Rahal
12/18/2024

How to Configure Obsidian LiveSync on Synology NAS Using Docker

ObsidianDockerSynologyDevOpsTutorial

Are you an Obsidian user on multiple devices with different operating systems and own a Synology NAS? Take advantage of Docker’s power to set up your own sync server and avoid paying for the Obsidian Sync subscription. In this article, I’ll guide you step by step through configuring the Obsidian LiveSync plugin using CouchDB on your Synology NAS.

Prerequisites

  • A Synology NAS with Portainer installed
  • Administrator access to your NAS
  • Basic knowledge of Docker

Step 1: Environment Preparation

  1. Create directories for Docker:

    • Open “File Station” on your Synology NAS.
    • Navigate to /volume1/docker/ or whatever path you have configured for Docker.
    • Create a new folder called obsidian-couchdb or whatever you prefer (if you change this name, update the script in Step 3 accordingly).
    • Inside obsidian-couchdb, create two subfolders: data and config.

  2. Configure permissions:

    • Make sure the user running Docker has read and write permissions on these folders.

Step 2: Configure the local.ini File

  1. Create the local.ini file:

    • In the /volume1/docker/obsidian-couchdb/config folder, create a file called local.ini.
    • Copy and paste the following content into local.ini:
[couchdb]
single_node=true
max_document_size = 50000000

[chttpd]
require_valid_user = true
max_http_request_size = 4294967296

[chttpd_auth]
require_valid_user = true
authentication_redirect = /_utils/session.html

[httpd]
WWW-Authenticate = Basic realm="couchdb"
enable_cors = true

[cors]
origins = app://obsidian.md,capacitor://localhost,http://localhost,https://obsidian.yourdomain.synology.me
credentials = true
headers = accept, authorization, content-type, origin, referer
methods = GET, PUT, POST, HEAD, DELETE
max_age = 3600

This file configures CouchDB to require authentication and allow requests from the Obsidian app. Note that we’ve added https://obsidian.yourdomain.synology.me to the list of allowed origins. This address will be configured in Step 4 when we set up the reverse proxy (optional).

Step 3: Configure the Docker Container with Portainer

  1. Access Portainer:

    • Open Portainer from the main menu of your Synology NAS.

  2. Create a new stack:

    • Click “Stacks” in the side menu.
    • Press “Add stack” to create a new one.

  3. Configure the stack using the following script:

version: "3.9"
services:
  couchdb:
    image: couchdb:latest
    container_name: CouchDB-Obsidian
    hostname: couchdb-obsidian
    mem_limit: 2g
    ports:
      - 5984:5984
    volumes:
      - /volume1/docker/obsidian-couchdb/data:/opt/couchdb/data
      - /volume1/docker/obsidian-couchdb/config:/opt/couchdb/etc/local.d
    environment:
      COUCHDB_USER: your_user
      COUCHDB_PASSWORD: your_password
      PUID: 1026 # Change this to your NAS Docker user's UID
      PGID: 100 # Change this to the GID of the 'users' group on your NAS
    restart: unless-stopped

Parameter explanation:

  • image: Specifies the CouchDB image to use.
  • container_name: Container name for easy identification.
  • hostname: Hostname inside the container.
  • mem_limit: Limits the memory the container can use.
  • ports: Maps the internal container port to the external NAS port.
  • volumes: Maps local folders to directories inside the container for data and configuration persistence.
  • environment: Variables that configure credentials and permissions:
    • COUCHDB_USER and COUCHDB_PASSWORD: Username and password for accessing CouchDB.
    • PUID and PGID: User and group identifiers ensuring files created by the container have the correct permissions.
  • restart: Configures the container to restart automatically if stopped.
  1. Deploy the stack:
    • Click “Deploy the stack” to start CouchDB.

To securely access your CouchDB from outside your local network, configure a reverse proxy:

  1. Set up a reverse proxy on Synology:
  • Go to “Control Panel” > “Application Portal”.
  • Select the “Reverse Proxy” tab.
  • Click “Create” and enter the following:
    • Description: “Obsidian CouchDB” or whatever you prefer
    • Source protocol: HTTPS (requires SSL certificate)
    • Hostname: obsidian.yourdomain.synology.me (your domain)
    • Source port: 443
    • Destination protocol: HTTP
    • Destination hostname: localhost
    • Destination port: 5984
  1. Configure SSL (if using HTTPS):
  • Make sure you have a valid SSL certificate for your domain configured under “Security” > “Certificate”.

Step 5: Configure the LiveSync Plugin in Obsidian on Primary and Secondary Devices

To configure the Self-hosted LiveSync plugin on your devices, follow these steps:

  1. Primary device:

    • Install the Self-hosted LiveSync plugin in Obsidian.
    • Configure the plugin with your CouchDB server URI (for example, https://obsidian.yourdomain.synology.me or http://YOUR_NAS_IP:5984). Note: Using http may cause issues on mobile devices.
    • Enter the username and password you configured for CouchDB in the previous steps.
    • Choose a name for the database (for example, “my_obsidian_vault”).
    • Enable the “Create database if it doesn’t exist” option.
    • Save the configuration and sync your vault (this may take a while).
    • Generate a URI with a passphrase (don’t lose it).

  2. Secondary devices:

    • Install the Self-hosted LiveSync plugin in Obsidian.
    • On the primary device, find the “Copy current settings as a new setup URI” option.
    • The plugin will show automatic setup guidance; paste this URI and use the passphrase you configured on the primary device.
    • Save the configuration and sync your vault (this may take a while).

With this setup, all your devices will sync through your CouchDB server on the Synology NAS, keeping your notes up to date everywhere.

Conclusions

This is a beta plugin, so I recommend always keeping backups of your vaults.

If you’re not very experienced, I recommend not playing with the plugin’s advanced options.

Keep in mind that only content is synced — plugin configuration and installation is not shared for compatibility reasons (it can be enabled in the advanced area, but I don’t recommend it as it tends to end in disaster).

The plugin works extremely well based on my testing over several weeks. The only thing not recommended is editing the same note on different devices simultaneously, as it will generate version conflicts that you’ll need to resolve.

Otherwise, it’s all advantages. So congratulations! You now have your own Obsidian LiveSync sync server running on your Synology NAS. You can sync your Obsidian notes across all your devices without relying on external cloud services.