Obsidian + Self-Hosted LiveSync Setup
======================================

This guide walks through setting up Obsidian with the Self-hosted LiveSync
plugin, syncing to CouchDB at https://couchdb.kolpacksoftware.com.

The web-based Obsidian instance is accessible at:
  https://obsidian.kolpacksoftware.com

--------------------------------------------------------------------------------
DOCKER COMPOSE (obsidian/docker-compose.yml)
--------------------------------------------------------------------------------

services:
  obsidian:
    image: lscr.io/linuxserver/obsidian:latest
    container_name: obsidian
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - /srv/obsidian-config:/config
    ports:
      - 3050:3000
      - 3051:3001
    shm_size: "1gb"
    restart: unless-stopped

networks:
  default:
    external:
      name: npm-network

Notes:
  - Port 3050 = HTTP (KasmVNC web UI)
  - Port 3051 = HTTPS (KasmVNC web UI)
  - Vault files are stored inside the container at /config/obsidian/

--------------------------------------------------------------------------------
STEP 1: CREATE THE VAULT
--------------------------------------------------------------------------------

  1. Open Obsidian on your machine.
  2. On the welcome screen, click "Create new vault".
  3. Name it: Obsidian Vault
  4. Choose a location on your disk (default is fine).
  5. Click "Create".

--------------------------------------------------------------------------------
STEP 2: DISABLE THE BUILT-IN SYNC PLUGIN
--------------------------------------------------------------------------------

  1. Open Settings (gear icon, bottom-left).
  2. Click "Core plugins" in the left sidebar.
  3. Find "Sync" in the list and toggle it OFF.

--------------------------------------------------------------------------------
STEP 3: INSTALL SELF-HOSTED LIVESYNC PLUGIN
--------------------------------------------------------------------------------

  1. In Settings, click "Community plugins".
  2. If prompted, click "Turn on community plugins".
  3. Click "Browse" and search for: Self-hosted LiveSync
  4. Click the result, then click "Install".
  5. Once installed, click "Enable".

--------------------------------------------------------------------------------
STEP 4: CONFIGURE LIVESYNC (ADDING A DEVICE)
--------------------------------------------------------------------------------

On the existing/primary device (e.g. https://obsidian.kolpacksoftware.com):

  1. Go to Settings → Self-hosted LiveSync.
  2. Click the wizard icon and select "Setup".
  3. Click "Copy" to generate a Setup URI.
  4. Set a passcode when prompted.
  5. Copy the URI to your clipboard.

On the new device:

  1. Go to Settings → Self-hosted LiveSync.
  2. Click the wizard icon.
  3. Select "I am adding a device".
  4. Select "Use the copied setup URI".
  5. Paste the Setup URI and enter the passcode.
  6. Click "Restart and Fetch Data".
  7. When prompted, select "This vault is empty, initialize with remote data".
  8. Click "I understand the risks" to confirm.

Obsidian will restart and sync the vault contents down from CouchDB.

--------------------------------------------------------------------------------
STEP 5: ENABLE LIVESYNC MODE
--------------------------------------------------------------------------------

  Once the initial sync completes:

  1. Go to Settings → Self-hosted LiveSync.
  2. Find "Synchronization Method".
  3. Set it to "LiveSync".

  This enables real-time continuous sync across all connected devices.

--------------------------------------------------------------------------------
TROUBLESHOOTING
--------------------------------------------------------------------------------

  - "CORS error" in browser console:
      CouchDB needs CORS enabled. Go to https://couchdb.kolpacksoftware.com/_utils
      (Fauxton UI), open Config, and under "cors" set:
        enable_cors  = true
        origins      = *
        credentials  = true
        methods      = GET, PUT, POST, HEAD, DELETE
        headers      = accept, authorization, content-type, origin, referer

  - "401 Unauthorized":
      Verify admin username/password in LiveSync settings.

  - Sync not starting:
      Toggle the plugin off and back on, or restart Obsidian.
      Check the LiveSync log panel (Settings → Self-hosted LiveSync → Log).

  - KasmVNC clipboard issues:
      Use the clipboard icon in the KasmVNC toolbar to paste text into
      the Obsidian window.
