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

docs/setup_flyio.md

@@ -12,7 +12,7 @@ This is how to configure fly.io and CouchDB on it for Self-hosted LiveSync.
 > **What and why is the Fly.io?**  
 > At some point, we started to experience problems related to our IBM Cloudant account. At the same time, Self-hosted LiveSync started to improve its functionality, requiring CouchDB in a more natural state to use all its features.
 >
-> Then we found Fly.io. Fly.io is the PaaS Platform, which can be useable for a very reasonable price. It generally falls within the `Free Allowances` range in most cases.
+> Fly.io charges according to current account and resource usage, including Machines, persistent volumes, and network usage. Check [Fly.io pricing](https://fly.io/pricing/) and the [pricing documentation](https://fly.io/docs/about/pricing/) before deploying. A time-limited trial does not provide ongoing free hosting.
 
 ## Required materials
 
@@ -31,10 +31,10 @@ This is how to configure fly.io and CouchDB on it for Self-hosted LiveSync.
 4. Copy the Setup-URI and Use it in the Obsidian.
 5. You have been synchronised. Use the Setup-URI in subsequent devices.
 
-Steps 4 and 5 are detailed in the [Quick Setup](./quick_setup.md#1-using-setup-uris).
+For steps 4 and 5, see [Set up the first device](./quick_setup.md#set-up-the-first-device), then [Add another device](./quick_setup.md#add-another-device) for subsequent devices.
 
 > [!NOTE]
-> Your automatically configured configurations will be shown on the result in the Colab note like below, and **it will not be saved**. Please make a note of it somewhere.
+> Save your own generated connection details and Setup URI securely. This is a historical Colab output example from 2024; its values are illustrative and will differ for each deployment. Replace all example credentials before deployment.
 > ```
 > -- YOUR CONFIGURATION --
 > URL     : https://billowing-dawn-6619.fly.dev
@@ -45,16 +45,18 @@ Steps 4 and 5 are detailed in the [Quick Setup](./quick_setup.md#1-using-setup-u
 
 ### B. Scripted Setup
 
-Please refer to the document of [deploy-server.sh](../utils/readme.md#deploy-serversh).
+Please refer to the document of [deploy-server.sh](../utils/readme.md#flyio-deployment).
 
 ### C. Manual Setup
 
 | Used in the text | Meaning and where to use    | Memo                                                                     |
 | ---------------- | --------------------------- | ------------------------------------------------------------------------ |
-| campanella       | Username                    | It is less likely to fail if it consists only of letters and numbers.    |
-| dfusiuada9suy    | Password                    |                                                                          |
+| `<YOUR UNIQUE COUCHDB USERNAME>` | Username                    | Choose a unique value using only letters and numbers.                     |
+| `<YOUR UNIQUE COUCHDB PASSWORD>` | Password                    | Generate a strong, unique password for this instance.                     |
 | nrt              | Region to make the instance | We can use any [region](https://fly.io/docs/reference/regions/) near us. |
 
+Choose an available, unique Fly.io application name and replace both credential placeholders before deployment. Historical output below illustrates the command responses; use your own application name, hostname, and credentials.
+
 #### 1. Install flyctl
 
 - Mac or Linux
@@ -97,8 +99,8 @@ For more information, please refer to [Sign up](https://fly.io/docs/hands-on/sig
 
 
 ```bash
-$ fly launch --name=billowing-dawn-6619 --env="COUCHDB_USER=campanella" --copy-config=true --detach --no-deploy --region nrt --yes
-$ fly secrets set COUCHDB_PASSWORD=dfusiuada9suy
+$ fly launch --name='<YOUR UNIQUE APP NAME>' --env="COUCHDB_USER=<YOUR UNIQUE COUCHDB USERNAME>" --copy-config=true --detach --no-deploy --region nrt --yes
+$ fly secrets set COUCHDB_PASSWORD='<YOUR UNIQUE COUCHDB PASSWORD>'
 ```
 
 #### 4. Deploy
@@ -177,17 +179,17 @@ This section is set up using the REST API.
 - Mac or Linux:
 
 ```bash
-export couchHost=https://billowing-dawn-6619.fly.dev
-export couchUser=campanella
-export couchPwd=dfusiuada9suy
+export couchHost='https://<YOUR APP HOSTNAME>'
+export couchUser='<YOUR UNIQUE COUCHDB USERNAME>'
+export couchPwd='<YOUR UNIQUE COUCHDB PASSWORD>'
 ```
 
 - Windows
 
 ```powershell
-set couchHost https://billowing-dawn-6619.fly.dev
-set couchUser campanella
-set couchPwd dfusiuada9suy
+set couchHost 'https://<YOUR APP HOSTNAME>'
+set couchUser '<YOUR UNIQUE COUCHDB USERNAME>'
+set couchPwd '<YOUR UNIQUE COUCHDB PASSWORD>'
 $creds = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("${couchUser}:${couchPwd}"))
 ```
 
@@ -242,11 +244,11 @@ Note: Each of these should also be repeated until finished in 200.
 
 #### 6. Use it from Self-hosted LiveSync
 
-Now the CouchDB is ready to use from Self-hosted LiveSync. We can use `https://billowing-dawn-6619.fly.dev` in URI, `campanella` in `Username` and `dfusiuada9suy` in `Password` on Self-hosted LiveSync. The `Database name` could be anything you want.
-Please refer to the [Minimal Setup of the Quick Setup](./quick_setup.md#2-minimal-setup).
+Now the CouchDB is ready to use from Self-hosted LiveSync. Use your Fly.io app's hostname in `URI`, and the unique credentials configured above in `Username` and `Password`. The `Database name` could be anything you want.
+Please refer to [Configure CouchDB manually on the first device](./quick_setup.md#configure-couchdb-manually-on-the-first-device).
 
 ## Delete the Instance
 
 If you want to delete the CouchDB instance, you can do that in [fly.io Dashboard](https://fly.io/dashboard/personal)
 
-If you have done with [B. Scripted Setup](#b-scripted-setup), we can use [delete-server.sh](../utils/readme.md#delete-serversh).
+If you have done with [B. Scripted Setup](#b-scripted-setup), we can use [delete-server.sh](../utils/readme.md#flyio-deployment).

docs/setup_object_storage.md

@@ -18,14 +18,14 @@ The public generator applies the Object Storage preset and records the connectio
 
 ```sh
 export remote_type=s3
-export endpoint=https://objects.example.com
-export access_key=<ACCESS KEY>
-export secret_key=<SECRET KEY>
+export endpoint='https://objects.example.com'
+export access_key='<ACCESS KEY>'
+export secret_key='<SECRET KEY>'
 export bucket=vault-data
 export region=auto
 export bucket_prefix=my-vault
-export LIVESYNC_PASSPHRASE=<A STRONG VAULT ENCRYPTION PASSPHRASE>
-export uri_passphrase=<A SEPARATE SETUP URI PASSPHRASE>
+export LIVESYNC_PASSPHRASE='<A STRONG VAULT ENCRYPTION PASSPHRASE>'
+export uri_passphrase='<A SEPARATE SETUP URI PASSPHRASE>'
 deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/setup/generate_setup_uri.ts
 ```
 

docs/setup_own_server.md

@@ -122,14 +122,14 @@ The `username` and `password` in this step are CouchDB administrator credentials
 
 ```
 export hostname=http://localhost:5984
-export username=<INSERT COUCHDB ADMINISTRATOR USERNAME HERE>
-export password=<INSERT COUCHDB ADMINISTRATOR PASSWORD HERE>
+export username='<INSERT COUCHDB ADMINISTRATOR USERNAME HERE>'
+export password='<INSERT COUCHDB ADMINISTRATOR PASSWORD HERE>'
 export database=obsidiannotes
 curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | bash
 ```
 
 > [!TIP]
-> In fish, `hostname` is read-only and cannot be exported. Pass the values through `env` instead: `curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | env hostname=http://localhost:5984 username=<...> password=<...> database=obsidiannotes bash`.
+> In fish, `hostname` is read-only and cannot be exported. Pass the values through `env` instead: `curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | env hostname='http://localhost:5984' username='<INSERT COUCHDB ADMINISTRATOR USERNAME HERE>' password='<INSERT COUCHDB ADMINISTRATOR PASSWORD HERE>' database=obsidiannotes bash`.
 
 If it results like the following:
 ```
@@ -140,7 +140,7 @@ The wrapper runs the exact registry-pinned Commonlib consumer. When `database` i
 
 If you are using Docker Compose and the above command does not work or displays `ERROR: Hostname missing`, you can try running the following command, replacing the placeholders with your own values:
 ```
-curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | hostname=http://<YOUR SERVER IP>:5984 username=<INSERT COUCHDB ADMINISTRATOR USERNAME HERE> password=<INSERT COUCHDB ADMINISTRATOR PASSWORD HERE> database=obsidiannotes bash
+curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | hostname='http://<YOUR SERVER IP>:5984' username='<INSERT COUCHDB ADMINISTRATOR USERNAME HERE>' password='<INSERT COUCHDB ADMINISTRATOR PASSWORD HERE>' database=obsidiannotes bash
 ```
 
 ## 3. Expose CouchDB to the Internet
@@ -148,13 +148,13 @@ curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/co
 - You can skip this instruction if you using only in intranet and only with desktop devices.
   - For mobile devices, Obsidian requires a valid SSL certificate. Usually, it needs exposing the internet.
 
-Whatever solutions we can use. For simplicity, the following sample uses Cloudflare Zero Trust for testing.
+For temporary testing, create a Cloudflare Quick Tunnel by following the [Quick Tunnels instructions](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/). It prints a random hostname which changes each time you create a tunnel, and the URL stops working when the `cloudflared` process stops. Quick Tunnels are intended for testing and development, not production. See the [Cloudflare Tunnel guide](https://developers.cloudflare.com/tunnel/get-started/) for durable use.
 
 ```
 cloudflared tunnel --url http://localhost:5984
 ```
 
-You will then get the following output:
+The following 2024 output is an example of the format. Its hostname is illustrative only; use the URL printed by your own tunnel instead.
 
 ```
 2024-02-14T10:35:25Z INF Thank you for trying Cloudflare Tunnel. Doing so, without a Cloudflare account, is a quick way to experiment and try it out. However, be aware that these account-less Tunnels have no uptime guarantee. If you intend to use Tunnels in production you should use a pre-created named tunnel by following: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps
@@ -167,7 +167,7 @@ You will then get the following output:
   :
   :
 ```
-Now `https://tiles-photograph-routine-groundwater.trycloudflare.com` is our server. Make it into the background once, please.
+Use the URL printed by your tunnel as the server address. Keep the tunnel process running while you configure and test the client.
 
 
 ## 4. Client Setup
@@ -179,12 +179,12 @@ Now `https://tiles-photograph-routine-groundwater.trycloudflare.com` is our serv
 The `LIVESYNC_USER` and `LIVESYNC_PASS` here are the credentials which Self-hosted LiveSync will store for routine access to this database. They may be the administrator credentials from step 2. If you have separately configured a CouchDB account with the required access to this database, use that account instead. Neither the provisioning wrapper nor the Setup URI generator creates that separate account.
 
 ```bash
-export LIVESYNC_HOST=https://tiles-photograph-routine-groundwater.trycloudflare.com
+export LIVESYNC_HOST='<YOUR QUICK-TUNNEL URL>'
 export LIVESYNC_DB=obsidiannotes
-export LIVESYNC_USER=<INSERT COUCHDB USERNAME FOR LIVESYNC>
-export LIVESYNC_PASS=<INSERT THE COUCHDB PASSWORD>
-export LIVESYNC_PASSPHRASE=<INSERT A STRONG VAULT ENCRYPTION PASSPHRASE>
-export uri_passphrase=<INSERT A SEPARATE SETUP URI PASSPHRASE> # Optional
+export LIVESYNC_USER='<INSERT COUCHDB USERNAME FOR LIVESYNC>'
+export LIVESYNC_PASS='<INSERT THE COUCHDB PASSWORD>'
+export LIVESYNC_PASSPHRASE='<INSERT A STRONG VAULT ENCRYPTION PASSPHRASE>'
+export uri_passphrase='<INSERT A SEPARATE SETUP URI PASSPHRASE>' # Optional
 deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/setup/generate_setup_uri.ts
 ```
 
@@ -199,9 +199,9 @@ The generator consumes the exact registry-pinned Commonlib release used by the p
 
 By default, the URI is Ephemeral and can be opened only until the exact UTC time printed by the generator. This is the end of a fixed seven-day window, not seven days after creation. Set `uri_mode=persistent` before running the command if the URI needs no time condition or must be readable by an older client that supports the existing encrypted format.
 
-You will then get the following output:
+The output has the following form. The timestamp and values below are illustrative:
 
-```bash
+```text
 Generated couchdb Setup URI.
 Ephemeral: usable until 2026-10-01T00:00:00.000Z (UTC).
 Your passphrase for the Setup URI is: H7vX...a-random-32-character-value

docs/setup_p2p.md

@@ -127,11 +127,11 @@ The public Setup URI generator is also available when configuration must be crea
 
 ```sh
 export remote_type=p2p
-export p2p_relays=wss://relay.example.com
-export p2p_room_id=<A PRIVATE ROOM ID> # Optional; generated when omitted
-export p2p_passphrase=<A PRIVATE P2P PASSPHRASE> # Optional; generated when omitted
-export LIVESYNC_PASSPHRASE=<A STRONG VAULT ENCRYPTION PASSPHRASE>
-export uri_passphrase=<A SEPARATE SETUP URI PASSPHRASE>
+export p2p_relays='wss://relay.example.com'
+export p2p_room_id='<A PRIVATE ROOM ID>' # Optional; generated when omitted
+export p2p_passphrase='<A PRIVATE P2P PASSPHRASE>' # Optional; generated when omitted
+export LIVESYNC_PASSPHRASE='<A STRONG VAULT ENCRYPTION PASSPHRASE>'
+export uri_passphrase='<A SEPARATE SETUP URI PASSPHRASE>'
 deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/setup/generate_setup_uri.ts
 ```
 

docs/tips/fast-setup.md

@@ -1,8 +1,8 @@
 # Fast Setup (Simple Fetch)
 
-Fast Setup is a streamlined, user-friendly data retrieval and initialisation flow designed to simplify setting up secondary devices or recovering databases. 
+Fast Setup (Simple Fetch) is the preferred flow for initial replication to a new or empty secondary device. It can also be used for recovery, but a retrieval choice may replace local files. Preserve valuable local and remote copies before choosing how to handle a Vault that already contains work. See [Recovery and flag files](../recovery.md#first-choose-the-authoritative-copy) for guidance on identifying the authoritative copy.
 
-Instead of guiding the user through the detailed multi-step setup wizard dialogues, Fast Setup prompts the user with high-level sync decisions and automates database download and local storage scanning in one continuous process.
+Instead of guiding the user through the detailed multi-step setup wizard dialogues, Fast Setup prompts the user with high-level synchronisation decisions and automates data retrieval and local storage scanning in one process. The retrieval path depends on the selected remote.
 
 ---
 
@@ -16,14 +16,14 @@ On the next startup, the plug-in boots in scheduled fetch mode and opens a simpl
 
 ## Technical Characteristics
 
-Fast Setup leverages several backend optimisations to make the retrieval fast, safe, and clean:
+Fast Setup uses several retrieval and reflection behaviours:
 
-1. **Stream-based Replication for Speed**
-   - It fetches all remote metadata via stream reception, which is significantly faster than traditional chunk-by-chunk retrieval.
+1. **Stream-based Fast Fetch for CouchDB**
+   - The stream-based Fast Fetch path is CouchDB-specific. It retrieves remote Metadata incrementally; Object Storage and P2P use their own retrieval paths.
 2. **Delayed File Reflection to Prevent Corrupted Warnings**
-   - By suspending file reflection during the download phase, it prevents the plug-in from raising temporary or false "corrupted data synchronisation" or "size mismatch" warnings that can occur during the chunk download process.
-3. **Time-Based Comparison is Generally Sufficient**
-   - Since the vault is entering a fresh synchronisation or recovery state, comparing files based on their modification timestamps (newer-wins) is highly reliable and sufficient to reconcile files without needing complex manual conflict resolution.
+   - Delaying local file reflection during retrieval suppresses temporary synchronisation warnings while remote data is being fetched.
+3. **Timestamp Comparison Selects a Whole File**
+   - **Compare time and take newer** compares modification timestamps and selects one whole-file version. It does not merge file contents. Before choosing this policy for a Vault with existing work, preserve valuable local and remote edits and review [Recovery and flag files](../recovery.md#first-choose-the-authoritative-copy).
 
 ---
 
@@ -33,11 +33,11 @@ Fast Setup leverages several backend optimisations to make the retrieval fast, s
 You will be prompted to choose how the retrieved remote data will interact with your existing local files:
 
 1. **Compare time and take newer (newer-wins)**
-   - Compares the modified time of files and accepts the newer version.
-   - **Recommended if:** You have been using Self-hosted LiveSync and have made changes on multiple devices that you want to merge.
+   - Compares the modified time of files and selects the newer whole-file version; it does not combine edits from both versions.
+   - **Recommended if:** You have preserved both versions and deliberately want to select one according to its modification time.
 2. **Overwrite all with remote files (remote-wins)**
    - Remote data is treated as the source of truth.
-   - **Recommended if:** You are setting up a brand new device with an empty or clean vault.
+   - **Recommended if:** You are setting up a new secondary device with an empty Vault.
    - *Warning: This will overwrite local files with remote files. Please ensure you have a backup of your local vault before proceeding.*
 3. **Use the detailed flow (legacy)**
    - Switches back to the detailed, traditional setup wizard dialogues.

utils/readme.md

@@ -55,13 +55,13 @@ The generator defaults to `uri_mode=ephemeral`. The URI opens only during the cu
 
 ```sh
 export remote_type=s3
-export endpoint=https://objects.example.com
-export access_key=<ACCESS KEY>
-export secret_key=<SECRET KEY>
+export endpoint='https://objects.example.com'
+export access_key='<ACCESS KEY>'
+export secret_key='<SECRET KEY>'
 export bucket=vault-data
 export region=auto
 export bucket_prefix=team-a # Optional
-export LIVESYNC_PASSPHRASE=<A STRONG VAULT ENCRYPTION PASSPHRASE>
+export LIVESYNC_PASSPHRASE='<A STRONG VAULT ENCRYPTION PASSPHRASE>'
 deno run --minimum-dependency-age=0 --config=./flyio/deno.jsonc --frozen --lock=./flyio/deno.lock --allow-env ./setup/generate_setup_uri.ts
 ```
 
@@ -71,7 +71,7 @@ Optional Object Storage variables are `use_custom_request_handler`, `force_path_
 
 ```sh
 export remote_type=p2p
-export LIVESYNC_PASSPHRASE=<A STRONG VAULT ENCRYPTION PASSPHRASE>
+export LIVESYNC_PASSPHRASE='<A STRONG VAULT ENCRYPTION PASSPHRASE>'
 deno run --minimum-dependency-age=0 --config=./flyio/deno.jsonc --frozen --lock=./flyio/deno.lock --allow-env ./setup/generate_setup_uri.ts
 ```