Correct setup and server operation guidance

docker/.env.example

@@ -34,9 +34,9 @@ ACME_EMAIL=you@yourdomain.com
 # PROFILE: tailscale  (--profile tailscale)
 # =============================================================================
 
-# Tailscale OAuth key (not a regular auth key — must be OAuth for persistent use)
-# Generate at: https://login.tailscale.com/admin/settings/oauth
-# Scopes needed: devices:write
+# Tailscale authentication key for this container.
+# OAuth clients require their own scopes and tag configuration; see:
+# https://tailscale.com/docs/features/containers/docker/docker-params#ts_authkey
 TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
 # Hostname this node will have on your tailnet (becomes <hostname>.<tailnet>.ts.net)
@@ -47,6 +47,6 @@ TS_HOSTNAME=livesync
 # =============================================================================
 
 # Tunnel token from Cloudflare Zero Trust dashboard
-# Create at: https://one.dash.cloudflare.com/ → Networks → Tunnels → Create tunnel
+# Current setup guide: https://developers.cloudflare.com/tunnel/get-started/
 # Copy the token from the "Install connector" step
 CF_TUNNEL_TOKEN=eyJhIjoixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

docker/README.md

@@ -61,11 +61,11 @@ docker compose --profile cloudflare up -d
 
 ```bash
 # Should return {"status":"ok"}
-curl -u admin:yourpassword http://localhost:5984/_up
+curl -u '<COUCHDB_USER>:<COUCHDB_PASSWORD>' http://localhost:5984/_up
 
 # Check CORS headers
 curl -v -H "Origin: app://obsidian.md" \
-     -u admin:yourpassword \
+     -u '<COUCHDB_USER>:<COUCHDB_PASSWORD>' \
      http://localhost:5984/
 ```
 
@@ -75,7 +75,7 @@ In the Obsidian plugin settings (**Self-hosted LiveSync**):
 
 | Field | Value |
 |---|---|
-| URI | `https://your-domain-or-ts-hostname:5984` (or `http://localhost:5984` for LAN-only) |
+| URI | `https://your-domain-or-ts-hostname` for an HTTPS profile, or `http://localhost:5984` for local HTTP |
 | Username | value of `COUCHDB_USER` |
 | Password | value of `COUCHDB_PASSWORD` |
 | Database name | value of `COUCHDB_DATABASE` (default: `obsidiannotes`) |
@@ -85,10 +85,13 @@ In the Obsidian plugin settings (**Self-hosted LiveSync**):
 
 ## Profile Details
 
-### Default (no profile) — LAN / Localhost only
+<a id="default-no-profile--lan--localhost-only"></a>
 
-CouchDB is exposed on `http://localhost:5984` (or LAN IP).  
-**Desktop Obsidian works over HTTP.** Mobile Obsidian requires HTTPS — use a tunnel profile.
+### Default (no profile) — Host HTTP access
+
+The Compose file publishes CouchDB on host port 5984 by default, on all host interfaces. Its reachability depends on the host firewall and network; selecting an HTTPS profile does not close that direct HTTP port. Restrict the host port to the intended network, bind it to loopback, or remove the mapping when all access uses the proxy.
+
+Desktop Obsidian can use HTTP. Use HTTPS for mobile clients and connections outside a trusted local network. The supplied HTTPS profiles use port 443, so their client URL normally has no `:5984` suffix.
 
 ### `--profile caddy` — Public Domain + Auto TLS
 
@@ -104,13 +107,14 @@ ACME_EMAIL=you@example.com
 
 Caddy automatically issues a Let's Encrypt certificate. No manual cert management.
 
-### `--profile tailscale` — No Domain Required ✅ Recommended for privacy
+<a id="--profile-tailscale--no-domain-required--recommended-for-privacy"></a>
+
+### `--profile tailscale` — Tailnet or public HTTPS
 
 **Requires**:
-- Free [Tailscale account](https://login.tailscale.com/)
-- Install the Tailscale app on all your Obsidian devices
-- Generate an **OAuth key** at: https://login.tailscale.com/admin/settings/oauth  
-  (Scopes: `devices:write`)
+- A [Tailscale account](https://login.tailscale.com/).
+- The Tailscale app on devices using private tailnet access.
+- An authentication key for `TS_AUTHKEY`. Follow the [Docker authentication parameters](https://tailscale.com/docs/features/containers/docker/docker-params#ts_authkey) if using an OAuth client instead.
 
 **Set in `.env`**:
 ```
@@ -118,34 +122,22 @@ TS_AUTHKEY=tskey-auth-...
 TS_HOSTNAME=livesync
 ```
 
-**Two sub-modes**:
-- **VPN mode** (default): CouchDB accessible only to devices on your Tailnet at  
-  `https://livesync.<tailnet>.ts.net` — completely private
-- **Funnel mode**: public HTTPS at `https://livesync.<tailnet>.ts.net` — no domain purchase  
-  Enable in your [Tailscale ACL](https://login.tailscale.com/admin/acls):
-  ```json
-  "nodeAttrs": [{"target": ["tag:container"], "attr": ["funnel"]}]
-  ```
+Choose the exposure before starting the profile. The bundled `config/ts-serve.json` sets `AllowFunnel` to `true`, requesting public HTTPS when the tailnet permits Funnel. It is not a private-only default.
 
-> **Note on Windows Docker Desktop**: If `/dev/net/tun` is unavailable, add `TS_USERSPACE=true`  
-> to the tailscale service environment in `docker-compose.yml`.
+- For private tailnet access, set that entry to `false` and verify the effective Serve configuration.
+- For public Funnel access, retain `true` and configure the required tailnet permissions. See the [Tailscale Docker guide](https://tailscale.com/blog/docker-tailscale-guide) for the distinction between Serve and Funnel.
+
+The bundled service expects `/dev/net/tun`. On hosts without that device, follow Tailscale's userspace-networking instructions and adjust the device mount as well as `TS_USERSPACE`; changing the environment variable alone leaves the required bind mount in place.
 
 ### `--profile cloudflare` — Cloudflare Tunnel
 
 **Requires**:
-- Free [Cloudflare account](https://www.cloudflare.com/)
-- A domain managed by Cloudflare DNS (can transfer existing domain for free)
-- Cloudflare Zero Trust account (free)
+- A [Cloudflare account](https://www.cloudflare.com/).
+- A domain whose DNS is managed by Cloudflare.
 
 #### Step 1: Create a Cloudflare Tunnel
 
-1. Log in to [Cloudflare Zero Trust](https://one.dash.cloudflare.com/)
-2. Navigate to **Networks → Tunnels**
-3. Click **Create a tunnel**
-4. Choose **Cloudflared** as tunnel type
-5. Name your tunnel (e.g., `obsidian-livesync`)
-6. Click **Save tunnel**
-7. **Copy the tunnel token** — it looks like `eyJhIjoiZX...` (very long, ~400 characters)
+Create a remotely managed tunnel using the current [Cloudflare Tunnel setup instructions](https://developers.cloudflare.com/tunnel/get-started/). Copy its connector token into `CF_TUNNEL_TOKEN` below. This Compose profile runs the connector; a separate host installation of `cloudflared` is unnecessary for this profile.
 
 #### Step 2: Configure Environment
 
@@ -157,27 +149,14 @@ COUCHDB_DOMAIN=sync.yourdomain.com   # Must be a domain managed by Cloudflare
 
 #### Step 3: Add Public Hostname Route
 
-🚨 **CRITICAL**: Token-based tunnels ignore the local `cloudflared.yml` config file. All routing is controlled from the dashboard.
+Configure the route in the Cloudflare dashboard for this remotely managed tunnel. The local `config/cloudflared.yml` is not the routing source for the token-managed profile.
 
-Back in the Zero Trust dashboard, **in the same tunnel creation flow** (or edit your tunnel later):
+1. Open the tunnel under **Networking → Tunnels**.
+2. Under **Routes**, add a **Published application**.
+3. Choose the public hostname, for example `sync.yourdomain.com`.
+4. Set the service URL to `http://couchdb:5984` and save the route.
 
-1. Go to the **Public Hostname** tab
-2. Click **Add a public hostname**
-3. Configure:
-   - **Subdomain**: `sync` (or your preferred subdomain)
-   - **Domain**: Select your Cloudflare domain from dropdown
-   - **Type**: `HTTP`
-   - **URL**: `couchdb:5984` ← **Do NOT use `localhost`!**
-
-**Why `couchdb:5984` not `localhost:5984`?**
-- The `cloudflared` container runs inside Docker on the same network as `couchdb`
-- Docker's internal DNS resolves `couchdb` to the correct container
-- Using `localhost` would look inside the `cloudflared` container (nothing there)
-
-4. Under **Additional application settings** (expand):
-   - **No TLS Verify**: Leave **OFF** (CouchDB uses plain HTTP internally, that's fine)
-   - Leave other settings at defaults
-5. Click **Save hostname**
+The `cloudflared` and `couchdb` services share a Docker network. The service name reaches CouchDB; `localhost` would address the `cloudflared` container itself. The local connection is HTTP, while the public client URL is HTTPS. Keep TLS certificate verification enabled for any HTTPS origin you configure later. The [current setup guide](https://developers.cloudflare.com/tunnel/get-started/) describes the dashboard flow.
 
 #### Step 4: Start the Stack
 
@@ -203,7 +182,7 @@ You should see:
 curl -I https://sync.yourdomain.com
 
 # Should return {"couchdb":"Welcome",...}
-curl -u admin:yourpassword https://sync.yourdomain.com
+curl -u '<COUCHDB_USER>:<COUCHDB_PASSWORD>' https://sync.yourdomain.com
 ```
 
 If you get **404**, see Troubleshooting below.
@@ -220,9 +199,7 @@ In Obsidian → Settings → **Self-hosted LiveSync**:
 | Database name | value of `COUCHDB_DATABASE` from `.env` (default: `obsidiannotes`) |
 | End-to-end passphrase | *Choose your own* — never stored server-side |
 
-Under **Remote Database Configuration → Advanced**:
-- Enable: ✅ **Use Request API to avoid inevitable CORS problem**
-  (See "Known Issue" below for why this is critical)
+If browser requests encounter a CORS failure, consult [Use Request API](../docs/settings.md#use-request-api-to-avoid-inevitable-cors-problem). That setting selects Obsidian's HTTP request adapter. It does not select the synchronisation mode or remove Cloudflare's proxy limits.
 
 ---
 
@@ -241,13 +218,11 @@ docker logs livesync-cloudflared --tail 20
 
 **Fix**: The public hostname rule is missing or incorrect.
 
-1. Go to Zero Trust → Networks → Tunnels → your tunnel → **Edit**
-2. Click **Public Hostname** tab
-3. Verify a hostname exists with:
-   - Service Type: `HTTP`
-   - URL: `couchdb:5984` (NOT `localhost:5984`)
-4. If no hostname exists, add it (see Step 3 above)
-5. Wait 30 seconds for changes to propagate, then test again
+1. Open the tunnel's published application routes in the Cloudflare dashboard.
+2. Verify that the requested hostname maps to `http://couchdb:5984`.
+3. Add or correct the route if required, then retry after the configuration has propagated.
+
+A connected tunnel alone does not establish that the hostname route or origin is correct.
 
 **Problem: Connection immediately closes / 502 Bad Gateway**
 
@@ -258,10 +233,10 @@ docker ps --filter "name=livesync-couchdb"
 # Status should be: Up (healthy)
 
 docker inspect livesync-couchdb -f '{{.NetworkSettings.Networks}}'
-# Should show: livesync-net
+# Both services should list the same Compose network.
 
 docker inspect livesync-cloudflared -f '{{.NetworkSettings.Networks}}'
-# Should also show: livesync-net
+# Compare with the CouchDB network above.
 ```
 
 **Fix**: If CouchDB is unhealthy, check logs:
@@ -271,41 +246,35 @@ docker logs livesync-couchdb --tail 50
 
 **Problem: 524 Timeout Errors During Sync**
 
-**Root cause**: Cloudflare's proxy has a **100-second idle timeout**. CouchDB's replication protocol uses long-polling on the `_changes` feed, which can idle for longer during quiet periods.
+A `524` can indicate that the origin did not respond or accept request data within Cloudflare's proxy timeout. Inspect the failing request, CouchDB response times, and connector logs before selecting a remedy. See [Cloudflare's current 524 guidance](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-524/) for the applicable limits and diagnostic steps.
 
-**Fix**: Switch to short-polling mode in the Obsidian plugin:
-1. Obsidian → Settings → Self-hosted LiveSync
-2. **Remote Database Configuration → Advanced**
-3. Enable: ✅ **Use Request API to avoid inevitable CORS problem**
-4. Save and restart sync
-
-This keeps all requests under 100 seconds.
-
-**Alternative**: Use Tailscale or Caddy profiles instead — neither has aggressive timeouts.
+**Use Request API** changes the HTTP adapter; it does not turn LiveSync mode into short polling or guarantee that a request completes within a proxy timeout. Review the actual synchronisation mode and [heartbeat/timeout setting](../docs/settings.md#use-timeouts-instead-of-heartbeats), then verify transfers on the intended devices. If the required traffic does not fit the proxy limits, consider an appropriately secured direct HTTPS route through Caddy or private Tailscale access.
 
 ---
 
 ## Data & Backup
 
-All vault data lives in the `couchdb-data` Docker named volume.
+The server database files live in the `couchdb-data` Docker named volume. Keep Vault backups, encryption passphrases, and ID recovery information separately. Back up the Compose configuration and CouchDB configuration as well; the database volume alone does not contain all of them.
+
+The following example creates an archive while CouchDB is stopped. Verify the volume name before running it, especially if you have overridden the Compose project name:
 
 ```bash
-# Backup
-docker run --rm -v obsidian-livesync_couchdb-data:/data \
-  -v $(pwd)/backup:/backup alpine \
-  tar czf /backup/couchdb-backup-$(date +%Y%m%d).tar.gz -C /data .
-
-# Restore
-docker run --rm -v obsidian-livesync_couchdb-data:/data \
-  -v $(pwd)/backup:/backup alpine \
-  tar xzf /backup/couchdb-backup-20260218.tar.gz -C /data
+docker volume inspect obsidian-livesync_couchdb-data
+mkdir -p backup
+docker compose stop couchdb
+docker run --rm --network none -v obsidian-livesync_couchdb-data:/data:ro \
+  -v "$(pwd)/backup:/backup" alpine \
+  tar czf "/backup/couchdb-backup-$(date +%Y%m%d-%H%M%S).tar.gz" -C /data .
+docker compose start couchdb
 ```
 
+Before restoration, preserve the existing database volume. Restore and verify the archive in a separate recovery volume with a compatible CouchDB installation before replacing the active data. Do not extract an archive over a running database. See [Backing up CouchDB](https://docs.couchdb.org/en/stable/maintenance/backups.html) for database, configuration, and replication-based backup options.
+
 ---
 
 ## Security Notes
 
-- CouchDB requires authentication for **all** requests (configured by `livesync.ini`)
+- The init service enables authenticated CouchDB access through the REST API. Verify that protected database endpoints reject unauthenticated requests before exposing the service.
 - Enable **End-to-End Encryption** passphrase in the Obsidian plugin — vault data is  
   encrypted before it ever leaves your device
 - The init container runs once and exits — it has no persistent access
@@ -344,8 +313,8 @@ open http://localhost:5984/_utils
 | Init container keeps restarting | CouchDB not healthy yet — wait 30s, check `docker compose logs couchdb` |
 | `curl: (52) Empty reply` | CouchDB not fully started — the healthcheck should gate this |
 | Mobile can't connect | Needs HTTPS — use tailscale or caddy profile |
-| 524 errors with Cloudflare | Enable "Use Request API" toggle in Obsidian plugin |
-| `Permission denied` on volumes | Run `docker compose down -v` and retry — first-run volume ownership issue |
+| 524 errors with Cloudflare | Inspect the failing request and origin response time; follow the timeout guidance above. |
+| `Permission denied` on volumes | Preserve the volume, inspect the CouchDB logs and mount ownership, and correct the specific permission problem. `docker compose down -v` deletes the database volume and is not a repair step. |
 | CORS errors in browser | Confirm CouchDB headers: `curl -v -H "Origin: app://obsidian.md" http://localhost:5984/` |
 | CouchDB exits immediately, zero logs (Windows) | **Do not add `:ro`** to the `livesync.ini` volume mount. CouchDB's entrypoint runs `chmod 0644` on all files in `/opt/couchdb/etc` — read-only bind mounts cause a silent EPERM crash on Docker Desktop for Windows (WSL2). The compose file is already correct; do not modify it. |
 | Settings in `livesync.ini` seem ignored | Settings requiring restart (e.g. bind_address) load at start. Runtime-only settings (require_valid_user, enable_cors) are set by the init container via REST API and take effect immediately without restart. |

docker/config/cloudflared.yml

@@ -2,17 +2,16 @@
 # =============================================================================
 #
 # Prerequisites:
-#   1. Create a tunnel in Cloudflare Zero Trust → Networks → Tunnels
+#   1. Create a remotely managed tunnel using the current Cloudflare dashboard guide.
 #   2. Copy the tunnel token to CF_TUNNEL_TOKEN in your .env
-#   3. Add a public hostname in the tunnel config:
+#   3. Add a published application route in the dashboard:
 #       Hostname : couchdb.yourdomain.com   (or whatever you set COUCHDB_DOMAIN to)
 #       Service  : http://couchdb:5984
 #
-# Known issue: Cloudflare's 100-second proxy timeout can interrupt CouchDB's
-# long-polling replication change feed, causing 524 errors.
-# MITIGATION: In the Obsidian plugin settings, enable:
-#   "Use Request API to avoid inevitable CORS problem"
-# This switches from long-poll to short-poll mode.
+# The token-managed Compose profile uses dashboard routing. The local ingress
+# example below describes locally managed routing and is not that profile's
+# source of routes. Diagnose 524 errors using current Cloudflare guidance.
+# The Obsidian Request API setting changes the HTTP adapter, not the sync mode.
 #
 # =============================================================================
 
@@ -23,7 +22,7 @@ ingress:
   - hostname: ${COUCHDB_DOMAIN}
     service: http://couchdb:5984
     originRequest:
-      # Increase timeouts for CouchDB replication streams
+      # Origin connection settings for this locally managed example
       connectTimeout: 30s
       keepAliveTimeout: 90s
       keepAliveConnections: 100

docker/config/livesync.ini

@@ -1,10 +1,9 @@
 ; CouchDB local configuration for Self-hosted LiveSync
-; This file is volume-mounted into /opt/couchdb/etc/local.d/livesync.ini
+; This file is volume-mounted into /opt/couchdb/etc/local.ini
 ;
-; IMPORTANT: Do NOT set require_valid_user here.
-; CouchDB needs to start without auth to complete its first-run cluster setup
-; (_users, _replicator databases must be created first).
-; The couchdb-init service applies auth lockdown via REST API after first-run.
+; The couchdb-init service configures require_valid_user and CORS through the
+; REST API during provisioning. Verify that the init service completes before
+; exposing the database to clients.
 
 [couchdb]
 ; Max size per document (50MB). Large enough for binary attachments.

docker/docker-compose.yml

@@ -2,7 +2,7 @@
 # =============================================================================
 #  PROFILES
 #  --------
-#  (default)              CouchDB only — LAN/localhost access, no TLS
+#  (default)              CouchDB only — host HTTP port, no TLS
 #                         Suitable for desktop-only use or testing.
 #
 #  --profile caddy        CouchDB + Caddy reverse proxy
@@ -14,7 +14,7 @@
 #
 #  --profile cloudflare   CouchDB + cloudflared tunnel daemon
 #                         Free public HTTPS via Cloudflare. Needs a CF account + tunnel token.
-#                         NOTE: Enable "Use Request API" in the Obsidian plugin to avoid 524 timeouts.
+#                         Review proxy timeouts separately from the Obsidian HTTP adapter setting.
 #
 #  QUICK START (local test):
 #    cp .env.example .env && edit .env
@@ -147,8 +147,8 @@ services:
   # PROFILE: cloudflare — cloudflared tunnel daemon
   # Requirements: Cloudflare account, tunnel token from CF Zero Trust dashboard
   # Usage: docker compose --profile cloudflare up -d
-  # NOTE: Enable "Use Request API" toggle in the Obsidian LiveSync plugin settings
-  #       to avoid Cloudflare's 100-second proxy timeout (524 errors).
+  # NOTE: The Request API setting changes the HTTP adapter, not the sync mode.
+  #       Diagnose proxy timeouts using the Docker README and current provider limits.
   # ---------------------------------------------------------------------------
   cloudflared:
     image: cloudflare/cloudflared:latest