From ec12e132827c2676542b9a57727fa3bcdec26f5f Mon Sep 17 00:00:00 2001 From: vorotamoroz Date: Wed, 28 Oct 2026 05:01:42 +0000 Subject: [PATCH] Correct recovery guidance and setup credential encoding Preserve Vault and remote data before deleting a Fly.io instance. Build cluster setup JSON with jq and ConvertTo-Json so credential characters remain intact. Also include the starting status icon and clarify the CouchDB hosting category. --- docs/README.md | 2 +- docs/setup_flyio.md | 35 +++++++++++++++++++++++++++++------ docs/tips/status-display.md | 1 + 3 files changed, 31 insertions(+), 7 deletions(-) diff --git a/docs/README.md b/docs/README.md index 79d97e6d..9c5499f9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,7 +10,7 @@ A document's original date and reviewed-version fields describe its baseline. Re |---|---| | Choose a synchronisation method | [Project overview and setup workflows](../README.md#setup-workflows) | | Set up CouchDB clients | [CouchDB server setup](setup_own_server.md), then [Quick setup](quick_setup.md) | -| Choose a packaged CouchDB deployment | [Docker stack](../docker/README.md), [Fly.io](setup_flyio.md), or [IBM Cloudant](setup_cloudant.md) | +| Choose a CouchDB hosting option | [Docker stack](../docker/README.md), [Fly.io](setup_flyio.md), or [IBM Cloudant](setup_cloudant.md) | | Set up S3-compatible storage | [Object Storage Setup](setup_object_storage.md) | | Set up peer-to-peer synchronisation | [P2P communication model](p2p.md), then [Peer-to-Peer Setup](setup_p2p.md) | | Diagnose P2P connectivity | [Browser-assisted check](../src/apps/webpeer/README.md#p2p-connection-check), [network tips](tips/p2p-sync-tips.md), and [self-hosted TURN](../docker/coturn/README.md) | diff --git a/docs/setup_flyio.md b/docs/setup_flyio.md index 0b926b3f..fcc3c1ee 100644 --- a/docs/setup_flyio.md +++ b/docs/setup_flyio.md @@ -4,9 +4,7 @@ This is how to configure fly.io and CouchDB on it for Self-hosted LiveSync. > [!WARNING] -> It is **your** instance. In Obsidian, we have files locally. Hence, do not hesitate to destroy the remote database if you feel something have got weird. We can launch and switch to the new CouchDB instance anytime[^1]. -> -[^1]: Actually, I am always building the database for reproduction of the issue like so. +> Before replacing or deleting an existing CouchDB instance, back up every available Vault and the remote database, then [choose the authoritative copy](recovery.md#first-choose-the-authoritative-copy). Stop or suspend synchronisation on other devices while reviewing recovery options. Local files alone do not establish that every needed edit or revision has been preserved. > [!NOTE] > **What and why is the Fly.io?** @@ -172,7 +170,7 @@ Visit your newly deployed app at https://billowing-dawn-6619.fly.dev/ After the initial setup, CouchDB needs some more customisations to be used from Self-hosted LiveSync. It can be configured in browsers or by HTTP-REST APIs. -This section is set up using the REST API. +This section uses the REST API. The macOS and Linux commands require [jq](https://jqlang.org/download/) to encode credentials as JSON. Windows uses PowerShell's built-in `ConvertTo-Json`. 1. Prepare environment variables. @@ -198,13 +196,36 @@ $creds = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes( - Mac or Linux ```bash -curl -X POST "${couchHost}/_cluster_setup" -H "Content-Type: application/json" -d "{\"action\":\"enable_single_node\",\"username\":\"${couchUser}\",\"password\":\"${couchPwd}\",\"bind_address\":\"0.0.0.0\",\"port\":5984,\"singlenode\":true}" --user "${couchUser}:${couchPwd}" +clusterSetupJSON=$(jq -n \ + --arg username "$couchUser" \ + --arg password "$couchPwd" \ + '{ + action: "enable_single_node", + username: $username, + password: $password, + bind_address: "0.0.0.0", + port: 5984, + singlenode: true + }') && +curl -X POST "${couchHost}/_cluster_setup" \ + -H "Content-Type: application/json" \ + --data-binary "$clusterSetupJSON" \ + --user "${couchUser}:${couchPwd}" ``` - Windows ```powershell -iwr -UseBasicParsing -Method 'POST' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds } "${couchHost}/_cluster_setup" -Body "{""action"":""enable_single_node"",""username"":""${couchUser}"",""password"":""${couchPwd}"",""bind_address"":""0.0.0.0"",""port"":5984,""singlenode"":true}" +$clusterSetupJSON = @{ + action = 'enable_single_node' + username = $couchUser + password = $couchPwd + bind_address = '0.0.0.0' + port = 5984 + singlenode = $true +} | ConvertTo-Json -Compress + +iwr -UseBasicParsing -Method 'POST' -ContentType 'application/json; charset=utf-8' -Headers @{ 'Authorization' = 'Basic ' + $creds } "${couchHost}/_cluster_setup" -Body $clusterSetupJSON ``` Note: if the response code is not 200. We have to retry the request once again. @@ -249,6 +270,8 @@ Please refer to [Configure CouchDB manually on the first device](./quick_setup.m ## Delete the Instance +Before deleting the instance, preserve the data you still need and follow [Recovery and flag files](recovery.md#first-choose-the-authoritative-copy). + 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#flyio-deployment). diff --git a/docs/tips/status-display.md b/docs/tips/status-display.md index 751d143e..d2cdf824 100644 --- a/docs/tips/status-display.md +++ b/docs/tips/status-display.md @@ -9,6 +9,7 @@ Use [General Settings](../settings.md#2-general-settings) to choose whether sync - 🌐N Approximate remote requests currently in progress - Status - ⏚ī¸ Stopped + - 🌀 Starting synchronisation - ⏊ Comparing CouchDB change history, including entries already held locally - 💤 LiveSync enabled. Waiting for changes - ⚡ī¸ Synchronisation in progress