Local Obsidian Sync

Using Self-hosted LiveSync plugin and CouchDB

Table of Contents

1. Project Overview & Architecture
   • Key Architectural Highlights
   • What It Is
   • The Stack
   • Why It's Cool
2. Prerequisites
3. Server Setup
4. Client Configuration
5. Maintenance and Useful Commands
• Service Management
• Monitoring and Logs
• Storage and Backups
6. Acknowledgements
7. License

Project Overview & Architecture

A private, end-to-end encrypted synchronization server for Obsidian, powered by Apache CouchDB and Docker, hosted locally on an Ubuntu server environment.

This repository contains the configuration files and documentation for a self-hosted synchronization backend designed specifically for the Obsidian Self-Hosted LiveSync plugin.

Instead of relying on third-party cloud storage or commercial sync services, this stack gives you complete ownership and control over your personal knowledge base while enabling seamless, real-time multi-device synchronization.

Key Architectural Highlights

• 100% Data Sovereignty: Your notes never leave your local network or infrastructure. Everything resides within your own Docker volumes and CouchDB database.
• End-to-End Encryption (E2EE): Data is encrypted on your client device before it is sent to the server. Even if the server were compromised, your notes remain completely private and unreadable.
• Real-Time Sync via LiveSync: Utilizes database change feeds to push and pull updates across your desktop and mobile devices instantly as you type.
• Lightweight & Containerized: Built using Docker Compose, making it trivial to deploy, back up, migrate, or spin up on alternative hardware (such as an old laptop or home server running Ubuntu).

What It Is

A self-hosted, containerized backend infrastructure using Apache CouchDB and Docker to provide real-time synchronization for Obsidian vaults across multiple devices.

The Stack

• OS: Ubuntu (running on local server hardware)
• Containerization: Docker & Docker Compose
• Database: Apache CouchDB (configured for persistent local storage and CORS access)
• Client Plugin: Obsidian Self-Hosted LiveSync

Why It's Cool

• Zero Cloud Reliance: Complete data ownership. No third-party servers, subscription fees, or hidden telemetry tracking your personal knowledge base.
• True End-to-End Encryption: Notes are encrypted locally on your client device before touching the server, ensuring absolute privacy.
• Instantaneous Multi-Device Sync: Leverages database change streams so your notes update across devices in real time as you edit.

Prerequisites

Before you begin setting up the synchronization server, ensure you have the following ready:

1. A Server Environment: A dedicated machine or old laptop running Ubuntu (or any Linux distribution capable of running Docker).
2. Obsidian: Installed on your client devices (Desktop and/or Mobile).
3. Obsidian Self-Hosted LiveSync Plugin: Installed via Obsidian's Community Plugins menu (make sure to enable community plugins in your vault settings).
4. Docker & Docker Compose: Installed and running on your host machine. You can verify this in your terminal by running:

BASH

# Verify the installation
sudo docker --version
sudo docker compose version

For secure, up-to-date installation steps tailored to your specific version of Ubuntu, please refer to the official documentation:

• Official Docker Engine Installation Guide for Ubuntu
• Docker Compose Installation Guide
• Tip: Ensure your user account is added to the docker group or use sudo for container commands.

Server Setup

Follow these steps to configure and run your self-hosted CouchDB server using Docker Compose.

Step 1: Clone or Create the Project Directory

On your Ubuntu server, create a dedicated directory for your sync stack and navigate into it:

BASH

mkdir obsidian-couchdb-sync
cd obsidian-couchdb-sync

Step 2: Create the docker-compose.yml File

Create a docker-compose.yml file in your project directory with the following configuration:

YAML

version: '3.8'

services:
  couchdb:
    image: couchdb:latest
    container_name: couchdb-sync
    restart: unless-stopped
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=${COUCHDB_USER}
      - COUCHDB_PASSWORD=${COUCHDB_PASSWORD}
    volumes:
      - couchdb_data:/opt/couchdb/data
      - ./local.ini:/opt/couchdb/etc/local.d/local.ini
volumes:
  couchdb_data

Step 3: Configure local.ini for LiveSync

The Self-Hosted LiveSync plugin requires specific CouchDB configurations (such as enabling CORS and adjusting cluster settings) to communicate properly.

Create a local.ini file in the same directory:

TOML

[couchdb]
single_node = true
max_document_size = 50000000

[httpd]
enable_cors = true
bind_address = 0.0.0.0

[cors]
origins = *
credentials = true
headers = accept, authorization, content-type, origin, referer
methods = GET, PUT, POST, HEAD, DELETE

[chttpd]
require_valid_user = true

Step 4: Launch the Server

Start your CouchDB container in detached mode using Docker Compose:

BASH

sudo docker compose up -d
sudo docker compose ps

Client Configuration

Once your CouchDB server is successfully running and accessible over your local network or VPN, configure your Obsidian clients to connect to it.

Step 1: Install the Plugin

1. Open Obsidian on your client device (Desktop or Mobile).
2. Go to Settings > Community plugins and ensure they are turned on.
3. Click Browse, search for Self-Hosted LiveSync, and click Install.
4. Once installed, click Enable.

Step 2: Configure Connection Settings

1. Open the plugin settings for Self-Hosted LiveSync.
2. Set up the connection URI pointing to your server's IP address and port:

 http://<YOUR_SERVER_IP>:5984

3. Enter the administrator credentials you defined in your .env file (COUCHDB_USER and COUCHDB_PASSWORD).
4. Create a unique database name for your vault sync (e.g., obsidian-vault-name).

Step 3: Run the Initial Synchronization

1. Choose your preferred synchronization mode (typically LiveSync or periodic sync depending on your preference).
2. Perform the initial database setup and migration check:
   • If setting up a new vault on a secondary device, pull the data from the server.
   • If pushing your primary vault for the first time, choose the option to upload your local vault to the remote database.
3. Verify that changes sync seamlessly across your devices.

Maintenance and Useful Commands

Manage, back up, and monitor your synchronization stack efficiently using standard Linux utilities and Docker Compose commands from your project directory.

Service Management

Start Services:

BASH

sudo docker compose up -d

Stop Services:

BASH

sudo docker compose down

Restart Services:

BASH

sudo docker compose restart

Monitoring and Logs

View Real-Time Container Logs

BASH

sudo docker compose logs -f

Check Container Status and Health

BASH

sudo docker compose ps

Storage and Backups

Check Disk Space Usage

BASH

sudo du -sh /var/lib/docker/volumes/* 2>/dev/null

Database Backups

CouchDB data is safely persisted inside the couchdb_data Docker volume. To back up your database, you can export or snapshot the volume data periodically, or use CouchDB's native replication/backup APIs.

Acknowledgements

• obsidian-livesync
• Best-README-Template

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)