Guide – Obsidian with free, self-hosted, instant sync

Docker Compose

Below is the docker compose file just to get CouchDB up and running:

version: "3.8"

services:
  couchdb-obsidian-livesync:
    container_name: obsidian-livesync #shortened name
    image: couchdb:3.3.3
    environment:
      - PUID=99
      - PGID=100
      - UMASK=0022
      - TZ=Asia/Ho_Chi_Minh
      - COUCHDB_USER=obsidian_user # optionally change me
      - COUCHDB_PASSWORD=obsidian_password # definitely change me
    volumes:
      - ./data:/opt/couchdb/data
      - ./etc/local.d:/opt/couchdb/etc/local.d
      - ./log:/opt/couchdb/var/log/couchdb # Added log volume
    ports:
      - "5984:5984"
    restart: unless-stopped
    labels:
      - net.unraid.docker.webui=http://[IP]:[PORT:5984]/_utils # This might need to be manually adjusted for the web UI
      - net.unraid.docker.icon=https://couchdb.apache.org/image/[email protected]
      - net.unraid.docker.shell=bash
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5984/_up"] # Healthcheck for CouchDB
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

CouchDB – Initial Configuration

1. Go to the CouchDB admin page by going here: http://10.10.10.13:5984/_utils make sure to use your server’s IP address.

2. Login using the credentials you set in the Docker compose file.

3. Click on the <-> icon on the top left, it will expand the menu from simple icons to icons with text which will make following this guide easier.

4. Click on Setup on the left menu.

5. Click on Configure as Single Node and enter the same credentials from the Docker compose file into the Specify your Admin credentials fields.

6. Leave everything else the same and click Configure Node.

CouchDB – Verify Installation

1. Let’s verify the CouchDB installation by clicking Verify on the left menu.

2. Click Verify Installation and if everything is good, a popup banner should popup saying Success! Your CouchDB installation is working. Time to Relax. along with 6 check marks next to each item in the table.

CouchDB – Create Database

1. Click on the Databases on the left menu.

2. Click on Create Database on the top right.

3. Under Database Name enter obsidiandb, or whatever you like. Advice: if you intend to use this setup for multiple users, each user will need their own database, so I recommend naming the database to include the user’s first name like: obsidiandb_john or obsidiandb_jane just to make it easier in the future.

4. Under Partitioning select Non-partitioned - recommended for most workloads. Once the database is created, you should be redirected to the new database’s config page. You don’t have to do anything here.

CouchDB – Configuration

1. Click on Configuration on the left main menu. The following 9 config entries are what the script was intended to do automatically but I wanted to do it manually. Click on + Add Option on the top right for each entry:

2. Section: chttpd Name: require_valid_user Value: true

3. Section: chttpd_auth Name: require_valid_user Value: true

4. Section: httpd Name: WWW-Authenticate Value: Basic realm="couchdb"

5. Section: httpd Name: enable_cors Value: true

6. Section: chttpd Name: enable_cors Value: true

7. Section: chttpd Name: max_http_request_size Value: 4294967296

8. Section: couchdb Name: max_document_size Value: 50000000

9. Section: cors Name: credentials Value: true

10. Section: cors Name: origins Value: `app://obsidian.md,capacitor://localhost,http://localhost

Obsidian – Windows 11 Client

1. Download and install the Windows 11 Obsidian client from here.

2. Once installed, open Obsidian.

3. Next to Create new vault click the Create button next.

4. In the Vault name field, name your Vault whatever you like, I simply named mine Vault. You can think of a vault as a "master folder" that contains all your folders and notes. Some users have different vaults for different aspects of their lives, such as Work or Personal but I keep everything under one vault for ease of use.

5. Next setting is Location, click Browse. This is where your vault will be locally saved. I created an Obsidian folder in the Documents folder but you can put it anywhere you like.

6. Click Create and Obsidian should open up to your newly created vault with 3 window panes. Next step is to setup the LiveSync plugin.

Obsidian – LiveSync Plugin

1. Click on options button (sprocket icon) on the bottom left area.

2. Click Community plugins and click on the Turn on community plugins button after reading the risk disclosure.

3. Next to Community plugins click on the Browse button.

4. Search for Self-hosted LiveSync.

5. Only 1 plugin should show up and that’s the one by voratamoroz, click on it.

6. Click the Install button and let it install.

7. Click the Enable button.

8. Click Open setting dialog button.

9. Click Options button.

10. Under Settings for Self-hosted LiveSync. you should see a row of 8 buttons, click on the 4th button with the 🛰️ satellite icon.

11. This is where we will enter the self-hosted CouchDB details. Next to Remote Type make sure CouchDB is selected from the drop down menu.

12. In the URI field type http://10.10.10.13:5984 make sure to change to your server IP and port. (Open the container online with HAProxy)

13. In the Username field type osidian_user or whatever you used in the docker compose.

14. Same for Password field.

15. In the Database name field type obsidiandb or whatever you named your database earlier in CouchDB.

16. Click the Test button to test the connection to the CouchDB database. Assuming everything is working properly a text popup should say Connected to obsidiandb successfully.

17. Click the Check button to confirm the database was configured properly, there should be a purple checkmark next to each line item. If not, there should be a Fix button next to the item that you can click for it to either create or correct for you, but I prefer to manually do it myself.

18. Assuming everything is good up to this point, click the Apply button next to Apply Settings.

19. Optional but recommended: scroll down to the End-to-end encryption and toggle it on and set a passphrase. Please remember this passphrase as all your other devices must have matching passphrases for it to be able to decrypt your notes. Click the red button Just apply.

20. On the top menu, under Settings for Self-hosted LiveSync. you should see a row of 8 buttons, click on the 5th button with the 🔄 refresh icon.

21. Next to Sync mode select LiveSync from the drop down menu.

22. You can close the settings windows out, on the top right of the notes you should see Sync: zZz which means everything is working properly and the sync is in standby mode until you start typing something.

23. Repeat the above instructions for all other devices.

Reverse Proxy

I highly recommend putting this behind at least a reverse proxy, I use Nginx Proxy Manager in conjunction with Cloudflare Tunnels. You will definitely need to if you plan on using mobile devices as they require HTTPS.