Skip to main content
Use a strong password for COUCHDB_PASSWORD and do not expose CouchDB directly to the public internet without proper reverse-proxy and access controls.

​
Server-side setup

1

Create working directory and base files

Create a Docker Compose directory and required files:
mkdir /opt/obsidian-sync && cd /opt/obsidian-sync && mkdir couchdb && mkdir couchdb/data && touch couchdb/local.ini && micro compose.yaml
2

Create compose.yaml

Add the following:
compose.yaml
services:
  couchdb:
    image: couchdb:latest
    container_name: obsidiansync
    environment:
      - TZ=Europe/Moscow # can be changed
      - COUCHDB_USER=YOUR_USERNAME # important
      - COUCHDB_PASSWORD=YOUR_LONG_PASSWORD # important
    volumes:
      - ./couchdb/data:/opt/couchdb/data
      - ./couchdb/local.ini:/opt/couchdb/etc/local.ini
    ports:
      - 5984:5984
    restart: unless-stopped
3

Run CouchDB setup in the web UI

  1. Navigate to http://127.0.0.1:5984/_utils.
  2. Click <-> to open the sidebar, then open Setup.
  3. Select Configure as single node and enter credentials from the compose file.
  4. Open Verify installation and confirm you see Success!.
  5. Go to Create Database, enter your preferred name, and select Non-partitioned.
4

Apply required CouchDB options

Navigate to Configuration and click + Add option.Add:
SectionOptionValue
chttpdrequire_valid_usertrue
chttpd_authrequire_valid_usertrue
httpdWWW-AuthenticateBasic realm=“couchdb”
httpdenable_corstrue
chttpdenable_corstrue
chttpdmax_http_request_size4294967296
couchdbmax_document_size50000000
corscredentialstrue
corsoriginsapp://obsidian.md,capacitor://localhost,http://localhost

​
Client-side setup

1

Install and open Self-hosted LiveSync

Open Obsidian, go to Settings -> Core Plugins, and install Self-hosted LiveSync.Then click Install -> Enable -> Open setting dialog -> Options.
2

Configure CouchDB connection

On the top icon row, click the 4th icon (🛰️) and set:
  • Remote type: CouchDB
  • URI: obsidian.domain.com
  • Username: YOUR_USERNAME
  • Password: YOUR_LONG_PASSWORD
  • Database: YOUR_DB_NAME
Click Test under Test Database connection and verify Connection successful!.Click Check under Validate Database and apply fixes if needed, then click Apply.
3

Configure sync mode

Go to the 5th subpage (🔄) and set:
  • Presets: Livesync
  • Sync mode: LiveSync
4

Enable status and finalize setup

  1. Open the 3rd subpage and enable the 2nd checkbox (status bar indicator).
  2. Open the 1st subpage, scroll down, and click I've read everything.
  3. Return to the 2nd subpage and click Enable under Enable LiveSync.
  4. If popups appear, click fetch and ignore size-limit notices if needed.
  5. Re-check sync mode from step 3.