Set Up Self-Hosted Obsidian Sync with Docker and CouchDB

What you’ll get

Your own private sync server for Obsidian notes, so your notes update in real time across your laptop, desktop, and phone, with no monthly subscription and your data staying entirely under your control. It runs CouchDB (a database good at syncing) inside Docker on a machine you own, and Obsidian’s LiveSync plugin talks to it. It is intermediate: you use a terminal and a couple of config files, but each is provided.

Tools you need

• Obsidian (freemium): the note-taking app you are syncing.
• Docker (freemium): runs CouchDB in a self-contained “container” so you do not install it by hand.
• CouchDB (free): the database that does the actual real-time syncing.
• Pinggy (free): gives your local server a secure public web address, so your phone can reach it without complex network setup.
• Obsidian LiveSync plugin (free): the Obsidian plugin that syncs your notes to CouchDB.

Steps

1. Install Docker: install Docker Desktop for your system and confirm it works with docker --version and docker compose version.

2. Make a project folder:

   mkdir obsidian-sync
   cd obsidian-sync

3. Create the config file: make a file named docker-compose.yml in that folder (this file describes the CouchDB service):

   touch docker-compose.yml

4. Configure CouchDB: open docker-compose.yml in a text editor and paste this, replacing the password with a strong one of your own:

   services:
     couchdb:
       image: couchdb:latest
       container_name: couchdb-for-ols
       environment:
         - COUCHDB_USER=admin
         - COUCHDB_PASSWORD=your-secure-password-here
       ports:
         - "5984:5984"
       volumes:
         - ./couchdb-data:/opt/couchdb/data

   This runs the official CouchDB, sets an admin user and password, exposes it on port 5984, and saves its data in a local couchdb-data folder so nothing is lost on restart.

5. Start CouchDB: from the same folder, run it in the background:

   docker compose up -d

   Check it is running with docker ps.

6. Open CouchDB: visit http://localhost:5984/_utils/ in your browser and log in with admin and your password. You should see CouchDB’s admin interface.

7. Expose it with Pinggy: sign up for Pinggy and start a tunnel to your local CouchDB on port 5984. This gives you a public HTTPS address your other devices can reach securely, without opening ports on your router.

8. Set up the Obsidian plugin: in Obsidian, go to Settings, then Community plugins, search for “Self-hosted LiveSync”, and install and enable it. In its settings, enter your Pinggy CouchDB URL, a database name, and the admin username and password. Repeat on each device so they all sync to the same server.

Original source

Based on a DEV Community guide by lightningdev123, sharing a free, private, self-hosted Obsidian sync setup using Docker and CouchDB after years of using Obsidian.

Notes & variations

• Free-tier alternative: Pinggy’s free tier works; for permanent remote access you could use another tunneling service or your own VPN if you have a static IP.
• Common pitfall: a weak or exposed CouchDB password. Always use a strong password and only reach CouchDB through the secure tunnel, or your notes could be exposed.
• Tip for better results: for large vaults or frequent edits, keep an eye on the server’s CPU, memory, and disk. CouchDB is efficient, but performance depends on your hardware.