Correct setup and server operation guidance

2026-10-29 20:43:20 +00:00 · 2026-10-27 13:14:38 +00:00
1 parent 2cfa4268cc
commit e17979e457
@@ -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).
@@ -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
 ```

@@ -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
@@ -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
 ```

@@ -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.