Self-Host Obsidian Sync with CouchDB

Why Self-Host Obsidian Sync?

Obsidian Sync costs $4/month ($48/year) per user. If you already run a server, you can replace it entirely with Obsidian LiveSync — a community plugin that syncs your vaults through a self-hosted CouchDB instance. You get real-time sync across unlimited devices, end-to-end encryption, and complete control over your data. No Obsidian account required.

Feature	Obsidian Sync ($4/mo)	Self-Hosted LiveSync
Cost	$48/year per user	Free (self-hosted)
Encryption	End-to-end	End-to-end (optional)
Device limit	Unlimited	Unlimited
Vault size limit	10 GB	Your server’s disk
Version history	12 months	CouchDB revisions
Selective sync	Yes	Yes
Real-time sync	Yes	Yes
Data location	Obsidian servers	Your server

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 1 GB of free disk space (plus your vault size)
• 512 MB of RAM minimum
• A domain name (recommended for HTTPS access)
• Obsidian installed on your devices

Docker Compose Configuration

CouchDB is the backend that Obsidian LiveSync uses to store and sync your vault data. Create a docker-compose.yml:

services:
  couchdb:
    image: couchdb:3.5.1
    container_name: obsidian-couchdb
    restart: unless-stopped
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=change-this-strong-password
    volumes:
      - couchdb-data:/opt/couchdb/data
      - couchdb-config:/opt/couchdb/etc/local.d
    ports:
      - "5984:5984"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:5984/_up || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

volumes:
  couchdb-data:
  couchdb-config:

Create a .env file:

# Change these values before starting
COUCHDB_USER=admin
COUCHDB_PASSWORD=change-this-strong-password

Start the stack:

docker compose up -d

Initialize CouchDB for LiveSync

After CouchDB starts, run the official initialization script. This configures CORS, creates required system databases, and sets the proper replication settings:

curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | bash

The script expects CouchDB at http://localhost:5984 with the credentials you set. If you’re running it remotely, set the environment variables first:

export hostname=your-server-ip:5984
export username=admin
export password=your-password
curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | bash

Verify CouchDB is running and initialized:

curl http://admin:your-password@localhost:5984/_all_dbs

You should see system databases like _users, _replicator, and _global_changes.

Install and Configure the Plugin

1. Open Obsidian → Settings → Community Plugins → Browse
2. Search for “Self-hosted LiveSync” and install it
3. Enable the plugin
4. Open the plugin settings → “Remote Configuration”
5. Enter your CouchDB connection details:
   • URI: https://your-domain.com:5984 (or http://your-server-ip:5984)
   • Username: your CouchDB admin username
   • Password: your CouchDB admin password
   • Database name: choose a name (e.g., obsidian-vault)
6. Click “Test” to verify the connection
7. Choose your sync mode:
   • LiveSync: Real-time sync as you type (recommended)
   • Periodic: Syncs at set intervals
   • On file open/close: Syncs when you switch notes

Configuration

End-to-End Encryption

In plugin settings → “Encryption”:

1. Enable “End to End Encryption”
2. Set a passphrase — use the same passphrase on all devices
3. All vault data is encrypted before leaving your device

Conflict Resolution

LiveSync handles merge conflicts automatically for most cases. Configure behavior under “Sync Settings”:

• Newer wins: The latest change takes precedence (default)
• Merge: Attempts to merge conflicting changes at the line level

Selective Sync

Under “Sync Settings” → “Hidden File Sync”:

• Choose which folders and file types to sync
• Exclude large binary files to save bandwidth
• Plugin settings can be synced separately

Reverse Proxy

For HTTPS access (strongly recommended), put CouchDB behind a reverse proxy. Here’s a Caddy snippet:

obsidian-sync.yourdomain.com {
    reverse_proxy localhost:5984
    header {
        Access-Control-Allow-Origin *
        Access-Control-Allow-Methods "GET, PUT, POST, HEAD, DELETE"
        Access-Control-Allow-Headers "accept, authorization, content-type, origin, referer"
        Access-Control-Max-Age 3600
    }
}

CORS headers are essential — without them, Obsidian’s web-based sync requests will fail. See our Reverse Proxy Setup guide for Nginx Proxy Manager and Traefik configurations.

Backup

CouchDB stores all data in the couchdb-data volume. Back up this volume regularly:

# Stop CouchDB for a consistent backup
docker compose stop couchdb
tar -czf couchdb-backup-$(date +%Y%m%d).tar.gz -C /var/lib/docker/volumes/ obsidian-couchdb_couchdb-data
docker compose start couchdb

Alternatively, use CouchDB’s built-in replication to mirror data to a second CouchDB instance for live backups. See our Backup Strategy guide.

Troubleshooting

Plugin says “Database is not found”

Symptom: Connection test passes but sync fails with “database not found.”

Fix: The database is created automatically on first sync. Make sure you entered the database name correctly in the plugin settings. If the issue persists, create it manually:

curl -X PUT http://admin:password@localhost:5984/obsidian-vault

CORS errors in Obsidian

Symptom: Sync fails with CORS-related errors in the developer console.

Fix: Re-run the initialization script, which sets CORS headers on CouchDB:

curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | bash

Or configure CORS manually:

curl -X PUT http://admin:password@localhost:5984/_node/_local/_config/httpd/enable_cors -d '"true"'
curl -X PUT http://admin:password@localhost:5984/_node/_local/_config/cors/origins -d '"*"'
curl -X PUT http://admin:password@localhost:5984/_node/_local/_config/cors/credentials -d '"true"'
curl -X PUT http://admin:password@localhost:5984/_node/_local/_config/cors/methods -d '"GET, PUT, POST, HEAD, DELETE"'
curl -X PUT http://admin:password@localhost:5984/_node/_local/_config/cors/headers -d '"accept, authorization, content-type, origin, referer, x-csrf-token"'

Sync is slow with large vaults

Symptom: Initial sync takes a very long time for vaults with thousands of notes.

Fix: First sync is always slower — CouchDB needs to replicate all documents. After the initial sync, incremental updates are fast. For vaults over 5,000 notes, consider:

• Using “Periodic” sync mode instead of “LiveSync” during initial setup
• Excluding binary files (images, PDFs) from sync
• Increasing CouchDB’s max_document_size if you have large attachments

CouchDB container won’t start — permission errors

Symptom: Container exits with permission denied errors on the data directory.

Fix: CouchDB runs as UID 5984 inside the container. If using bind mounts instead of named volumes, set ownership:

sudo chown -R 5984:5984 ./couchdb-data ./couchdb-config

Resource Requirements

Resource	Minimum	Recommended
RAM	256 MB	512 MB
CPU	Low	Low
Disk	1 GB + vault size	5 GB+

CouchDB is lightweight. A single-user vault with a few thousand notes uses under 200 MB of RAM. Multi-user setups with many concurrent syncs will need more.

Verdict

Obsidian LiveSync with CouchDB is the best free alternative to Obsidian Sync. Setup takes about 15 minutes, the real-time sync works reliably, and end-to-end encryption means your notes stay private even on your own server. The only downside is that it requires maintaining a CouchDB instance — but if you’re already self-hosting, that’s trivial.

If you want the simplest possible sync and don’t mind paying, official Obsidian Sync is more polished. But for anyone running a homelab, LiveSync is the clear choice. It supports unlimited vaults, unlimited devices, and costs nothing beyond the server you’re already running.

FAQ

Can I sync multiple vaults with one CouchDB instance?

Yes. Each vault uses a separate database in CouchDB. Just give each vault a unique database name in the plugin settings (e.g., vault-personal, vault-work).

Does this work with Obsidian on mobile?

Yes. The LiveSync plugin works on iOS and Android. Install the plugin on your mobile Obsidian, enter the same CouchDB connection details and encryption passphrase, and sync works identically.

Can multiple users share a CouchDB instance?

Yes. Create separate CouchDB databases for each user’s vault. For true multi-user collaboration on the same vault, LiveSync supports it — but be aware that concurrent editing of the same note can produce merge conflicts.

What happens if CouchDB goes down?

Your local Obsidian vault is always the primary copy. If CouchDB is unreachable, Obsidian works normally — changes queue up and sync when the connection is restored. No data is lost.

How does this compare to Syncthing for Obsidian?

Syncthing syncs files at the filesystem level, which can cause conflicts with Obsidian’s internal indexing. LiveSync operates at the document level through CouchDB, which is conflict-aware and handles concurrent edits more gracefully. LiveSync also supports real-time sync — Syncthing only polls at intervals.

Related

• Best Self-Hosted Note Taking Apps
• How to Self-Host Outline
• How to Self-Host Joplin Server
• Trilium vs Joplin: Which Should You Self-Host?
• SiYuan vs Obsidian: Which Should You Self-Host?
• Self-Hosted Alternatives to Notion
• Self-Hosted Alternatives to Evernote
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy