From c8050322e48502b16c377551772bf670e605918b Mon Sep 17 00:00:00 2001 From: vorotamoroz Date: Thu, 23 Jul 2026 16:46:50 +0000 Subject: [PATCH] Clarify remote setup and verify manual CouchDB onboarding --- docs/quick_setup.md | 24 +- docs/setup_own_server.md | 2 +- package.json | 1 + src/common/messages/combinedMessages.prod.ts | 32 +- src/common/messagesJson/en.json | 32 +- src/common/messagesYAML/en.yaml | 60 +-- .../dialogs/SelectMethodExisting.svelte | 7 +- .../dialogs/SelectMethodNewUser.svelte | 15 +- .../SetupWizard/dialogs/SetupRemote.svelte | 22 +- test/e2e-obsidian/README.md | 4 +- .../scripts/couchdb-manual-setup-workflow.ts | 369 ++++++++++++++++++ test/e2e-obsidian/scripts/dialog-mounts.ts | 8 +- test/e2e-obsidian/scripts/local-suite.ts | 4 + test/e2e-obsidian/scripts/run-focused.ts | 1 + 14 files changed, 492 insertions(+), 89 deletions(-) create mode 100644 test/e2e-obsidian/scripts/couchdb-manual-setup-workflow.ts diff --git a/docs/quick_setup.md b/docs/quick_setup.md index 3c8d3131..b156bcbe 100644 --- a/docs/quick_setup.md +++ b/docs/quick_setup.md @@ -100,6 +100,26 @@ Add optional features separately so that their ownership and initialisation dire Do not enable both features for the same files. -## Manual configuration +## Configure CouchDB manually on the first device -If a Setup URI is unavailable, choose `Enter the server information manually` during onboarding. Manual configuration is an advanced path: verify the connection, encryption, remote profile, and synchronisation preset before initialising either side. After the first device works, use `Copy settings as a new Setup URI` from the command palette to add later devices through the recommended path. +Use this path when CouchDB is ready but a Setup URI is unavailable. It configures one first device through the visible onboarding dialogue; it does not provision or repair the CouchDB server. Add later devices with a Setup URI generated by this working first device instead of entering the credentials again. + +1. Install and enable Self-hosted LiveSync in the intended Vault. +2. Select the `Welcome to Self-hosted LiveSync` Notice, choose `I am setting this up for the first time`, then confirm that you want to set up a new synchronisation. +3. On `Connection Method`, select `Configure a remote manually`, then select `Proceed with manual configuration`. +4. On `End-to-End Encryption`, decide how the synchronised data will be protected. + - For an ordinary new Vault, enable `End-to-End Encryption` and enter a strong Vault encryption passphrase. + - Enable `Obfuscate Properties` if remote document properties should also be concealed. + - Store the Vault encryption passphrase securely. It is separate from the passphrase used to protect a Setup URI. +5. On `Choose a synchronisation remote`, select `CouchDB`, then select `Continue to CouchDB setup`. +6. Enter the complete CouchDB URL, username, password, and database name. + - Obsidian Mobile requires HTTPS. Plain HTTP is suitable only for a trusted local connection from a desktop device. + - Use credentials which are allowed to connect to the selected database and, for this first-device path, create it when it does not exist. +7. `Check server requirements` is optional. It sends the displayed credentials to the configured server through Obsidian's internal request API, and some checks require CouchDB administrator access. The initial check is read-only. If it offers a server change, review and confirm that individual change separately. +8. Select `Create or connect to database and continue`. Onboarding requires this connection test to succeed. +9. Review `Setup Complete: Preparing to Initialise Server`, then select `Restart and Initialise Server`. +10. Read the final overwrite warning. Select `I Understand, Overwrite Server` only when this device is intentionally the source of truth and a current backup exists. +11. A newly created database can show `Fetch Remote Configuration Failed` because it does not yet contain a saved preferred configuration. Select `Skip and proceed` only for this known new database. +12. Acknowledge `All optional features are disabled`, then keep Obsidian open until the initialisation progress has cleared. + +Create and synchronise an ordinary test note. Once it has reached CouchDB, follow [Create a Setup URI for another device](#create-a-setup-uri-for-another-device), then [Add another device](#add-another-device). This keeps the second device aligned with the remote profile and encryption settings which the first device actually applied. diff --git a/docs/setup_own_server.md b/docs/setup_own_server.md index 47af4d55..6268413f 100644 --- a/docs/setup_own_server.md +++ b/docs/setup_own_server.md @@ -167,7 +167,7 @@ Now `https://tiles-photograph-routine-groundwater.trycloudflare.com` is our serv ## 4. Client Setup > [!TIP] -> Now manual configuration is not recommended for some reasons. However, if you want to do so, please use `Setup wizard`. The recommended extra configurations will be also set. +> A generated Setup URI is the recommended path because it carries the current new-Vault defaults and remote profile. If a Setup URI cannot be generated, follow [Configure CouchDB manually on the first device](./quick_setup.md#configure-couchdb-manually-on-the-first-device), then generate a new Setup URI from that working device for every additional device. ### 1. Generate the setup URI on a desktop device or server ```bash diff --git a/package.json b/package.json index 42c21c94..eb7a91a1 100644 --- a/package.json +++ b/package.json @@ -55,6 +55,7 @@ "test:e2e:obsidian:p2p-pane": "tsx test/e2e-obsidian/scripts/p2p-pane.ts", "test:e2e:obsidian:vault-reflection": "tsx test/e2e-obsidian/scripts/vault-reflection.ts", "test:e2e:obsidian:couchdb-upload": "tsx test/e2e-obsidian/scripts/couchdb-upload.ts", + "test:e2e:obsidian:couchdb-manual-setup-workflow": "tsx test/e2e-obsidian/scripts/couchdb-manual-setup-workflow.ts", "test:e2e:obsidian:cli-to-obsidian-sync": "tsx test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts", "test:e2e:obsidian:minio-upload": "tsx test/e2e-obsidian/scripts/minio-upload.ts", "test:e2e:obsidian:object-storage-setup-uri-workflow": "tsx test/e2e-obsidian/scripts/object-storage-setup-uri-workflow.ts", diff --git a/src/common/messages/combinedMessages.prod.ts b/src/common/messages/combinedMessages.prod.ts index 529229ca..00cfba16 100644 --- a/src/common/messages/combinedMessages.prod.ts +++ b/src/common/messages/combinedMessages.prod.ts @@ -8810,15 +8810,15 @@ export const allMessages: Readonly2- - This replicator allows us to synchronise our vault with other devices - using a peer-to-peer connection. We can use this to synchronise our vault - with our other devices without using a cloud service. + This replicator allows us to synchronise our vault with other devices + using a peer-to-peer connection. We can use this to synchronise our vault + with our other devices without using a cloud service. - This replicator is based on Trystero. It also uses a signalling server to - establish a connection between devices. The signalling server is used to - exchange connection information between devices. It does (or,should) not - know or store any of our data. + This replicator is based on Trystero. It also uses a signalling server to + establish a connection between devices. The signalling server is used to + exchange connection information between devices. It does (or,should) not + know or store any of our data. - The signalling server can be hosted by anyone. This is just a Nostr relay. - For the sake of simplicity and checking the behaviour of the replicator, - an instance of the signalling server is hosted by vrtmrz. You can use the - experimental server provided by vrtmrz, or you can use any other server. + The signalling server can be hosted by anyone. This is just a Nostr relay. + For the sake of simplicity and checking the behaviour of the replicator, + an instance of the signalling server is hosted by vrtmrz. You can use the + experimental server provided by vrtmrz, or you can use any other server. - By the way, even if the signalling server does not store our data, it can - see the connection information of some of our devices. Please be aware of - this. Also, be cautious when using the server provided by someone else. + By the way, even if the signalling server does not store our data, it can + see the connection information of some of our devices. Please be aware of + this. Also, be cautious when using the server provided by someone else. important_note: Peer-to-Peer Replicator. important_note_sub: This feature is still on the bleeding edge. Please be aware that ensure your data is backed up before using this feature. And, we @@ -1895,9 +1895,9 @@ Ui: Guidance: We will now guide you through a few questions to simplify the synchronisation setup. SelectExisting: Guidance: You are adding this device to an existing synchronisation setup. - ManualOption: Enter the server information manually - ManualOptionDesc: Configure the same server information as your other devices again manually. This is intended only for advanced users. - ProceedManual: I know my server details, let me enter them + ManualOption: Configure a remote manually + ManualOptionDesc: Configure the same remote as your other devices again manually. This is intended only for advanced users. + ProceedManual: Proceed with manual configuration ProceedQr: Scan the QR code displayed on an active device using this device's camera. ProceedSetupUri: Proceed with Setup URI Question: Please select a method to import the settings from another device. @@ -1907,14 +1907,14 @@ Ui: SetupUriOptionDesc: Paste the Setup URI generated from one of your active devices. Title: Device Setup Method SelectNew: - Guidance: We will now proceed with the server configuration. - ManualOption: Enter the server information manually - ManualOptionDesc: This is an advanced option for users who do not have a Setup URI or who want to configure detailed settings. - ProceedManual: I know my server details, let me enter them + Guidance: We will now configure the synchronisation connection. + ManualOption: Configure a remote manually + ManualOptionDesc: This is an advanced option for users who do not have a Setup URI or who want to configure detailed settings. You can also use it for P2P synchronisation instead of CouchDB or S3-compatible Object Storage. + ProceedManual: Proceed with manual configuration ProceedSetupUri: Proceed with Setup URI - Question: How would you like to configure the connection to your server? + Question: How would you like to configure this synchronisation connection? SetupUriOption: Use a Setup URI (Recommended) - SetupUriOptionDesc: A Setup URI is a single string containing your server address and authentication details. If one was generated by your server installation script, it provides a simple and secure configuration method. + SetupUriOptionDesc: A Setup URI is a single string containing connection and authentication details. When one is available from a setup script, it provides a simple and secure configuration method. Title: Connection Method OutroAskUserMode: CompatibleOption: The remote is already set up, and the configuration is compatible (or became compatible through this operation). @@ -1951,13 +1951,13 @@ Ui: Proceed: I Understand, Prepare This Device Title: "Final Confirmation: Prepare This Device for P2P" SetupRemote: - BucketOption: S3/MinIO/R2 Object Storage - BucketOptionDesc: Synchronisation using journal files. You must already have an S3/MinIO/R2 compatible object storage service set up. + BucketOption: S3-compatible Object Storage + BucketOptionDesc: Synchronisation using journal files. You must already have an S3-compatible Object Storage service set up, such as Amazon S3, MinIO, or Cloudflare R2. CouchDbOptionDesc: This is the most suitable synchronisation method for the current design. All features are available. You must already have a CouchDB instance set up. - Guidance: Please select the type of server you are connecting to. - P2POption: Peer-to-Peer only + Guidance: Select the remote type for this synchronisation setup. + P2POption: Peer-to-Peer (P2P) P2POptionDesc: This enables direct synchronisation between devices. No server is required, but both devices must be online at the same time and some features may be limited. Internet connectivity is required only for signalling, not for data transfer. - ProceedBucket: Continue to S3/MinIO/R2 setup + ProceedBucket: Continue to Object Storage setup ProceedCouchDb: Continue to CouchDB setup - ProceedP2P: Continue to Peer-to-Peer only setup - Title: Enter Server Information + ProceedP2P: Continue to P2P setup + Title: Choose a synchronisation remote diff --git a/src/modules/features/SetupWizard/dialogs/SelectMethodExisting.svelte b/src/modules/features/SetupWizard/dialogs/SelectMethodExisting.svelte index bebc78b6..c45cd727 100644 --- a/src/modules/features/SetupWizard/dialogs/SelectMethodExisting.svelte +++ b/src/modules/features/SetupWizard/dialogs/SelectMethodExisting.svelte @@ -7,6 +7,7 @@ import Options from "@/modules/services/LiveSyncUI/components/Options.svelte"; import Instruction from "@/modules/services/LiveSyncUI/components/Instruction.svelte"; import UserDecisions from "@/modules/services/LiveSyncUI/components/UserDecisions.svelte"; + import { $msg as translateMessage } from "@/common/translation"; import { TYPE_USE_SETUP_URI, TYPE_SCAN_QR_CODE, @@ -24,7 +25,7 @@ if (userType === TYPE_USE_SETUP_URI) { return "Proceed with Setup URI"; } else if (userType === TYPE_CONFIGURE_MANUALLY) { - return "I know my server details, let me enter them"; + return translateMessage("Ui.SetupWizard.SelectExisting.ProceedManual"); } else if (userType === TYPE_SCAN_QR_CODE) { return "Scan the QR code displayed on an active device using this device's camera."; } else { @@ -49,10 +50,10 @@ diff --git a/src/modules/features/SetupWizard/dialogs/SelectMethodNewUser.svelte b/src/modules/features/SetupWizard/dialogs/SelectMethodNewUser.svelte index d479cb8f..8f5d31fd 100644 --- a/src/modules/features/SetupWizard/dialogs/SelectMethodNewUser.svelte +++ b/src/modules/features/SetupWizard/dialogs/SelectMethodNewUser.svelte @@ -24,7 +24,7 @@ if (userType === TYPE_USE_SETUP_URI) { return "Proceed with Setup URI"; } else if (userType === TYPE_CONFIGURE_MANUALLY) { - return "I know my server details, let me enter them"; + return translateMessage("Ui.SetupWizard.SelectNew.ProceedManual"); } else { return "Please select an option to proceed"; } @@ -35,22 +35,19 @@ -We will now proceed with the server configuration. +{translateMessage("Ui.SetupWizard.SelectNew.Guidance")} - How would you like to configure the connection to your server? + {translateMessage("Ui.SetupWizard.SelectNew.Question")}