Sync Obsidian for Free with CouchDB: Step-by-Step Self-Hosted Guide

Obsidian is an exceptional tool for personal knowledge management because it operates strictly on plain markdown text files stored on your local machine. However, the moment you want to access your notes across multiple devices, such as a desktop PC, a MacBook, an Android phone, or an iPad, you run into the synchronization hurdle.

The official Obsidian Sync service is polished and well-engineered, but it costs money every single month. Free alternatives like iCloud Drive on Windows are notoriously unstable, while third-party cloud sync tools can lead to corrupted databases and merge collisions when files update simultaneously.

In this guide, we are building a production-grade, self-hosted synchronization engine using Apache CouchDB, Docker Compose, and the Self-Hosted LiveSync community plugin. This setup provides near-instantaneous live replication, end-to-end encryption, and full cross-platform compatibility across desktop and mobile devices without paying a subscription.

Why Apache CouchDB for Obsidian?

Unlike traditional relational databases like MySQL or PostgreSQL, Apache CouchDB is an open-source NoSQL document database built specifically for distributed, multi-master replication. CouchDB treats every revision of a document as an immutable snapshot with an internal revision ID. When two devices modify notes concurrently, CouchDB detects the divergence at the document level and provides deterministic conflict resolution algorithms.

When paired with the Self-Hosted LiveSync plugin created by vorot93, Obsidian connects directly to CouchDB over HTTP/HTTPS. Every keystroke and saved note triggers an incremental sync event. Your data is encrypted locally on your device with AES-GCM before it ever leaves your machine, ensuring that even if your server is hosted publicly, nobody can read your vault contents without your master encryption passphrase.

Prerequisites and System Architecture

Before we begin the setup, ensure you have the following elements in place:

• A Linux Host or LXC Container: An Ubuntu or Debian server (such as an LXC container running inside Proxmox VE) with at least 1 vCPU, 1 GB of RAM, and 10 GB of storage.
• Docker and Docker Compose: The Docker runtime installed on your host. If you are using a Proxmox LXC container, ensure Nesting is enabled in the container options so Docker can run smoothly.
• A Reverse Proxy or Domain (Recommended): An SSL-enabled reverse proxy such as Cloudflare Tunnels, Nginx Proxy Manager, or Caddy pointing to your CouchDB container port. This allows your mobile devices to sync securely over cellular networks.
• Obsidian Installed: Running on your primary desktop or workstation.

Understanding CORS (Cross-Origin Resource Sharing)

The most common roadblock when configuring CouchDB with web or hybrid applications like Obsidian is the browser security boundary known as CORS (Cross-Origin Resource Sharing).

Obsidian's internal engine is built on Electron and web technologies. When Obsidian attempts to send API requests from your local computer or phone to an external CouchDB server located on a different IP address, domain, or port, the security policy immediately rejects the connection unless CouchDB explicitly returns headers stating that cross-origin requests are permitted.

To prevent connection errors, we must configure CouchDB with a custom local.ini configuration file that explicitly enables CORS, permits all origins, and exposes the required headers.

Step 1: Preparing Directory Structure and CORS Configuration

Log into your Linux server or LXC container via SSH. We will create a dedicated directory for CouchDB to house our persistent database files and configuration templates.

# Create a dedicated directory on your storage drive
mkdir -p /data/couchdb/data
cd /data/couchdb

# Create the custom local.ini configuration file
nano local.ini

Paste the following configuration into local.ini. This enables CouchDB's native CORS engine and opens up the necessary methods and authentication headers that the LiveSync plugin requires:

[couchdb]
single_node=true
max_document_size = 50000000

[chttpd]
port = 5984
bind_address = 0.0.0.0
enable_cors = true

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

Save and exit the editor by pressing Ctrl+O, Enter, and Ctrl+X.

Step 2: Deploying CouchDB with Docker Compose

Next, we will define our container service using Docker Compose. In the same /data/couchdb directory, create a docker-compose.yml file:

nano docker-compose.yml

Insert the following service definition. Be sure to replace your_admin_username and your_strong_password with your actual credentials:

version: '3.8'

services:
  couchdb:
    image: couchdb:3.3.3
    container_name: couchdb_obsidian
    restart: unless-stopped
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=your_admin_username
      - COUCHDB_PASSWORD=your_strong_password
    volumes:
      - /data/couchdb/data:/opt/couchdb/data
      - ./local.ini:/opt/couchdb/etc/local.d/local.ini

Launch the container in detached mode:

docker compose up -d

Docker will pull the official CouchDB image, apply your custom configuration, and launch the service.

Step 3: Verifying the Server Response

Before opening Obsidian, confirm that CouchDB is healthy and responding over the network. You can test it locally via curl or by navigating to the URL in your web browser:

curl -X GET http://localhost:5984/

You should receive a clean JSON payload greeting you with the server information:

{
  "couchdb": "Welcome",
  "version": "3.3.3",
  "git_sha": "9143b2d13",
  "uuid": "d41d8cd98f00b204e9800998ecf8427e",
  "features": [
    "access-ready",
    "partitioned",
    "pluggable-storage-engines",
    "reshard",
    "scheduler"
  ],
  "vendor": {
    "name": "The Apache Software Foundation"
  }
}

If you have mapped your server behind a reverse proxy (e.g., https://sync.techsimpld.com), visit that URL in your browser. When you see the CouchDB welcome greeting, your backend database is fully operational.

Step 4: Installing and Configuring Self-Hosted LiveSync

Now we configure your primary Obsidian vault to push data to CouchDB:

1. Open Obsidian and click the Settings gear icon in the lower-left corner.
2. Navigate to Community plugins and turn off Restricted Mode if prompted.
3. Click Browse, search for Self-hosted LiveSync by vorot93, and click Install, then Enable.
4. In the left sidebar of the settings window, scroll down to the bottom and select Self-hosted LiveSync.
5. Click the button at the top labeled Rerun onboarding wizard (or Start setup wizard).
6. Select First device (since this is our initial setup).
7. Choose Configure remote manually.
8. Enable End-to-End Encryption (E2EE). Enter a reliable passphrase. Keep this passphrase secure in a password manager; you will need it to decrypt your notes on subsequent devices.
9. Under synchronization method, choose CouchDB.
10. Enter your server connection details:
    • URL: Your full HTTPS domain (e.g., https://sync.techsimpld.com) or local IP with port 5984.
    • Admin Username: The username you defined in your Docker Compose file.
    • Admin Password: The corresponding password.
    • Database Name: obsidian
11. Click Create or connect to database and continue.
12. When prompted, acknowledge the confirmation risks, and click Use this device's settings.

Step 5: Running the Config Doctor and Health Checks

Once connected, the plugin performs an initial database verification. A banner may appear indicating that synchronization is paused for a compatibility review.

Click Resume synchronization. The built-in Config Doctor will check your vault settings against recommended best practices:

• Chunk Size: The plugin may notify you that chunk size is unconfigured. Click Apply recommended settings to set the chunk size to 60. This optimizes file transfer chunks for markdown and attachments.
• Storage Limits: Under storage warning alerts, select a standard capacity (such as 2 GB) so the plugin notifies you well before your server runs low on disk space.

After adjusting these options, restart Obsidian once. Click the small circular sync/replicate icon in your status bar or command palette. You will see a notification stating: Replication has been completed successfully.

Step 6: Syncing Second Devices (Mac, Windows, iOS, Android)

Connecting secondary devices does not require re-typing complex URLs or database paths. The plugin includes an automated setup URI generator:

1. On your primary (configured) Obsidian vault, open Settings -> Self-hosted LiveSync.
2. Scroll down and select Copy current settings to a setup URI.
3. Set a temporary passphrase for the URI payload and copy the generated link.
4. On your second device (e.g., your laptop or mobile phone), install Obsidian and create an empty vault.
5. Install and enable the Self-hosted LiveSync plugin in that new vault.
6. In the plugin settings, select Connect with setup URI.
7. Paste the URI string, enter your temporary passphrase, and select My server is already set up and I want to join this device.
8. Choose your conflict handling preference: select Compare modification times and keep the newer version.
9. Enable file deletion synchronization (e.g., Delete local files if deleted on remote).

Within seconds, the plugin will authenticate with CouchDB, fetch the encrypted blobs, decrypt them locally with your master passphrase, and populate your entire folder structure and note library.

Troubleshooting Common CouchDB Sync Issues

If you encounter errors during initial replication, check these common configuration bottlenecks:

• Network Connection Failed (CORS Errors): If the status icon displays red connection errors, your reverse proxy or CouchDB instance is blocking origin headers. Verify that your local.ini file was properly mounted into the container volume at /opt/couchdb/etc/local.d/local.ini and that origins = * is active.
• Reverse Proxy Timeout on Large Vaults: If your initial sync contains hundreds of images or PDFs, standard Nginx or Cloudflare proxy timeouts (usually 60 seconds) can drop the connection mid-transfer. Increase client request timeouts and maximum body sizes (e.g., client_max_body_size 100M;) in your proxy configuration.
• Mobile Sync Freezes in Background: Both iOS and Android aggressively sleep background network processes for battery management. Keep Obsidian open on your mobile screen during the initial sync until all files are transferred. Subsequent edits transfer in fractions of a second.

Summary and Key Takeaways

By combining Apache CouchDB with the Self-Hosted LiveSync plugin, you break free from subscription fees and third-party cloud dependencies. Your notes remain completely your own, stored on your home server, protected by end-to-end encryption, and updated across every screen you own.

It delivers the integrated multi-device convenience of a paid cloud service with the rock-solid data sovereignty of a local-first home lab.

Official Documentation & Resources

• Self-Hosted LiveSync GitHub Repository
• Apache CouchDB Official Documentation
• Obsidian Note-Taking App