mirror of
https://github.com/vrtmrz/obsidian-livesync.git
synced 2026-07-25 05:53:00 +00:00
Use established terms in setup guidance
This commit is contained in:
vorotamoroz
@@ -200,7 +200,7 @@ Current implementation status:
|
||||
Current implementation status:
|
||||
|
||||
- The mocked Vitest browser suites, their P2P runner, their root-level relay helpers, and the manual `harness-ci` workflow have been removed after maintained suites covered the critical flows.
|
||||
- Headless CouchDB and Object Storage combinations, with and without encryption, remain owned by the CLI two-Vault matrix. P2P transport replacement and relay lifecycle remain owned by the CLI Compose E2E suite. Real Obsidian owns the visible CouchDB, Object Storage, and P2P Setup URI workflows, including first-device URI generation, second-device import, and two-way Vault synchronisation.
|
||||
- Headless CouchDB and Object Storage combinations, with and without encryption, remain owned by the CLI two-Vault matrix. P2P transport replacement and relay lifecycle remain owned by the CLI Compose E2E suite. Real Obsidian owns the visible CouchDB, Object Storage, and P2P Setup URI workflows, including URI generation on the first device, import on the second device, and two-way Vault synchronisation.
|
||||
- The Obsidian compatibility implementation still needed by the Webapp has moved to `src/apps/webapp/obsidianMock.ts`; it is not a retained browser E2E Harness.
|
||||
- Remaining high-value scenarios, including RedFlag and Fast Setup (Simple Fetch) variants, should be added according to their owning integration boundary rather than copied line by line from the retired suite.
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ Lifecycle operations on one `LiveSyncTrysteroReplicator` are serialised. A close
|
||||
|
||||
Relay sockets retain their Trystero-provided close handlers. LiveSync pauses relay reconnection, closes the sockets, and later resumes reconnection through Trystero's public functions. It does not replace `socket.onclose`, because Trystero uses that handler to retire and recreate shared relay clients correctly.
|
||||
|
||||
P2P setup follows the transport's actual ownership model. First-device initialisation resets and scans the local database, but does not attempt to lock, reset, or upload to a non-existent central remote database. Its confirmation dialogues therefore describe preparing this device and do not present the central-server overwrite warnings or remote-configuration option. An additional device performs one explicit peer-selection and finite Fetch pass, then resumes database and Vault reflection. The generic second convergence pass remains reserved for central remote types because repeating it for P2P would ask the user to select the same peer twice.
|
||||
P2P setup follows the transport's actual ownership model. Initialising the first device resets and scans the local database, but does not attempt to lock, reset, or upload to a non-existent central remote database. Its confirmation dialogues therefore describe preparing this device and do not present warnings about overwriting a central server or an option to fetch its configuration. An additional device selects a peer once, performs Fetch once, then resumes database and Vault reflection. The generic second convergence pass remains reserved for central remote types because repeating it for P2P would ask the user to select the same peer twice.
|
||||
|
||||
## Ownership
|
||||
|
||||
@@ -74,7 +74,7 @@ This interferes with Trystero's shared relay clients. The public pause and resum
|
||||
|
||||
## Verification
|
||||
|
||||
Commonlib unit tests prove that normal P2P host closure calls `room.leave()` without directly closing Trystero-owned peer connections. Additional package tests cover the action API, replaceable peer-event subscriptions, multiple RPC transport disposers, serialised open and close operations, local-only first-device initialisation, and one-pass additional-device Fetch.
|
||||
Commonlib unit tests prove that normal P2P host closure calls `room.leave()` without directly closing Trystero-owned peer connections. Additional package tests cover the action API, replaceable peer-event subscriptions, multiple RPC transport disposers, serialised open and close operations, initialisation of the first device without a central remote, and Fetch running once for an additional device.
|
||||
|
||||
Self-hosted LiveSync unit tests prove that settings and database replacement leave panes on the current replicator, and that an explicit P2P rebuild bypasses the policy intended for ordinary replication.
|
||||
|
||||
|
||||
+5
-5
@@ -53,7 +53,7 @@ The **P2P Status** pane is the current Obsidian interface for P2P connections.
|
||||
- LiveSync does not open the pane merely because Obsidian has started. If the pane was already part of the saved Obsidian workspace, Obsidian may restore it.
|
||||
- Workspaces containing the retired P2P pane are migrated to the current status pane. The retired command is no longer exposed.
|
||||
|
||||
The active P2P remote is selected independently from the main CouchDB or Object Storage remote. Devices can therefore use P2P as an additional transport without replacing their main remote.
|
||||
The active P2P remote is selected independently from the main CouchDB or Object Storage remote. Devices can therefore use P2P alongside their main remote without replacing it.
|
||||
|
||||
|
||||
|
||||
@@ -74,9 +74,9 @@ Every participating device must use the same signalling relay set, Group ID, and
|
||||
- A notification contains no Vault data. It only asks the following peer to fetch through the encrypted P2P connection.
|
||||
- Missing a notification does not make an explicit later synchronisation unsafe; **Replicate now** still compares the available data.
|
||||
|
||||
The peer's **More actions** menu contains persistent conveniences:
|
||||
The peer's **More actions** menu can save these choices for that device:
|
||||
|
||||
- **Synchronise when this device connects** runs a finite synchronisation when that named peer is discovered.
|
||||
- **Synchronise when this device connects** runs one synchronisation when that named peer is discovered.
|
||||
- **Follow whenever this device connects** restores following for that named peer.
|
||||
- **Include in the P2P synchronisation command** includes that peer when the command for registered targets is run.
|
||||
|
||||
@@ -88,11 +88,11 @@ Configure these only after a manual round trip has succeeded. Device names used
|
||||
|
||||
A device must approve a peer before serving its data. Permanent approval is stored; session approval lasts only for the current Obsidian session. Check the displayed device name before approving a request.
|
||||
|
||||
The encrypted Setup URI contains the shared P2P configuration but deliberately omits the device-specific name. Store the Setup URI and its passphrase separately, and generate the additional-device URI from a working first device.
|
||||
The encrypted Setup URI contains the shared P2P configuration but deliberately omits the device-specific name. Store the Setup URI and its passphrase separately, and generate a Setup URI for another device from a first device which has completed setup.
|
||||
|
||||
## Operational limits
|
||||
|
||||
- At least one device which already has the required data must be online while another device fetches it.
|
||||
- P2P does not provide the continuously available central copy offered by CouchDB or Object Storage. Keep independent backups.
|
||||
- Mobile operating systems may pause Obsidian in the background. Keep Obsidian visible and the device awake during initial transfer, rebuild, or a large finite synchronisation.
|
||||
- Mobile operating systems may pause Obsidian in the background. Keep Obsidian visible and the device awake during initial transfer, rebuild, or a large synchronisation.
|
||||
- Changing from CouchDB to P2P is not a repair operation for a stopped CouchDB setup. Diagnose the existing transport first.
|
||||
|
||||
@@ -2,6 +2,6 @@
|
||||
|
||||
This address is retained for links to an earlier P2P guide. The time-specific interface description has been replaced by stable documentation:
|
||||
|
||||
- [Set up peer-to-peer synchronisation](setup_p2p.md) for the first device, additional-device Setup URI, approval, and two-way verification.
|
||||
- [Set up peer-to-peer synchronisation](setup_p2p.md) for configuring the first device, generating a Setup URI for another device, approving the connection, and verifying synchronisation in both directions.
|
||||
- [How peer-to-peer synchronisation works](p2p.md) for signalling, TURN, privacy, the P2P Status pane, and automatic behaviour.
|
||||
- [Peer-to-Peer Synchronisation Tips](tips/p2p-sync-tips.md) for connection troubleshooting.
|
||||
|
||||
+5
-5
@@ -50,13 +50,13 @@ Create an ordinary test note and allow it to upload before adding another device
|
||||
|
||||
## Create a Setup URI for another device
|
||||
|
||||
Generate the additional-device Setup URI from the working first device. This captures the settings which that device is actually using, rather than asking another device to reuse the bootstrap URI produced during server provisioning.
|
||||
Generate a Setup URI for another device from the working first device. This captures the settings which that device is actually using, rather than asking another device to reuse the Setup URI produced during server provisioning.
|
||||
|
||||
1. Open the Obsidian command palette on the first device.
|
||||
2. Run `Self-hosted LiveSync: Copy settings as a new Setup URI`.
|
||||
3. Enter a new passphrase which will protect this Setup URI, then select `OK`.
|
||||
|
||||
|
||||
|
||||
|
||||
4. Copy the resulting Setup URI, then select `OK`.
|
||||
|
||||
@@ -75,7 +75,7 @@ Start with a new or separately backed-up Vault. Do not use a production Vault co
|
||||
5. Paste the new Setup URI generated by the first device, enter its Setup URI passphrase, and select `Test Settings and Continue`.
|
||||
6. Review `Setup Complete: Preparing to Fetch Synchronisation Data`, then select `Restart and Fetch Data`.
|
||||
|
||||
|
||||
|
||||
|
||||
7. For a new or empty Vault, select `Overwrite all with remote files`. For a Vault with local work, stop and choose the appropriate strategy from the [Fast Setup guide](./tips/fast-setup.md).
|
||||
|
||||
@@ -83,7 +83,7 @@ Start with a new or separately backed-up Vault. Do not use a production Vault co
|
||||
|
||||
8. When asked how to handle extra local files, the conservative choice is `Keep local files even if not on remote`. Select the delete option only when the local Vault is disposable and an exact remote copy is intended.
|
||||
|
||||
|
||||
|
||||
|
||||
9. Allow retrieval, file reflection, and any requested restart to finish. Keep Obsidian open until the LiveSync progress indicators have cleared.
|
||||
|
||||
@@ -114,7 +114,7 @@ Use this path when CouchDB is ready but a Setup URI is unavailable. It configure
|
||||
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.
|
||||
- Use credentials which are allowed to connect to the selected database and, when configuring the first device, create it if 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`.
|
||||
|
||||
+2
-2
@@ -14,7 +14,7 @@ Use the least destructive operation which matches the evidence:
|
||||
- If the correct data is uncertain, suspend all work with `redflag.md`, preserve every copy, and inspect them before proceeding.
|
||||
- If the central remote is healthy and should win, use **Reset Synchronisation on This Device** or `flag_fetch.md`.
|
||||
- If this device's Vault is healthy and should replace a damaged or unwanted central remote, use **Overwrite Server Data with This Device's Files** or `flag_rebuild.md`.
|
||||
- If both the Vault and local database are healthy and the only concern is unused storage, Garbage Collection may be appropriate. It is not a damaged-database recovery operation.
|
||||
- If both the Vault and local database are healthy and the only concern is unused storage, Garbage Collection may be appropriate. It does not repair a damaged database.
|
||||
|
||||
Do not switch transport, enable P2P, or run Garbage Collection as a substitute for diagnosing a stopped CouchDB or Object Storage setup.
|
||||
|
||||
@@ -58,7 +58,7 @@ The readable flag is `flag_rebuild.md`; the legacy name `redflag2.md` remains ac
|
||||
|
||||
For CouchDB and Object Storage, this is destructive to the selected remote state. Other devices may still contain revisions or files which are not present in the authoritative Vault, so keep them stopped until the new remote has been verified and then reset them from that remote.
|
||||
|
||||
For a P2P-only setup, there is no central remote database to overwrite. The corresponding first-device preparation rebuilds this device's local LiveSync database from its Vault.
|
||||
For a P2P-only setup, there is no central remote database to overwrite. Preparing the first device instead rebuilds its local LiveSync database from its Vault.
|
||||
|
||||
## Garbage Collection is not Rebuild
|
||||
|
||||
|
||||
+2
-2
@@ -386,8 +386,8 @@ The subject (`sub`) claim of the JWT, which should match your CouchDB username.
|
||||
|
||||
The action depends on why the dialogue was opened:
|
||||
|
||||
- First-device onboarding uses **Create or connect to database and continue**. It may create the database when it does not exist and the supplied account has permission.
|
||||
- Additional-device onboarding uses **Connect to existing database and continue**. It does not create a missing database.
|
||||
- Onboarding for the first device uses **Create or connect to database and continue**. It may create the database when it does not exist and the supplied account has permission.
|
||||
- Onboarding for an additional device uses **Connect to existing database and continue**. It does not create a missing database.
|
||||
- Adding or editing a saved remote profile uses **Test connection and save**. It does not create a missing database.
|
||||
- Settings mode also offers **Save without connecting**. The existing profile is updated, but automatic synchronisation may fail until the connection is corrected.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Set up Object Storage
|
||||
|
||||
This guide establishes Object Storage synchronisation on a first device, generates an additional-device Setup URI from that working device, and verifies synchronisation in both directions.
|
||||
This guide establishes Object Storage synchronisation on a first device, generates a Setup URI for another device from that working device, and verifies synchronisation in both directions.
|
||||
|
||||
Object Storage uses the S3-compatible API. Prepare the following before starting:
|
||||
|
||||
@@ -12,7 +12,7 @@ Object Storage uses the S3-compatible API. Prepare the following before starting
|
||||
|
||||
Back up every Vault involved, and do not use Obsidian Sync, iCloud synchronisation, or another synchronisation service on the same Vault.
|
||||
|
||||
## Generate the bootstrap Setup URI
|
||||
## Generate the initial Setup URI
|
||||
|
||||
The public generator applies the Object Storage preset and records the connection as the selected remote profile. Run it from a trusted terminal:
|
||||
|
||||
@@ -40,13 +40,13 @@ Use a new bucket prefix, or a prefix whose contents you deliberately intend to r
|
||||
1. Install and enable Self-hosted LiveSync in the intended Vault.
|
||||
2. Open onboarding from the `Welcome to Self-hosted LiveSync` Notice.
|
||||
3. Select `I am setting this up for the first time`, then choose the recommended Setup URI method.
|
||||
4. Paste the bootstrap Setup URI, enter its passphrase, and select `Test Settings and Continue`.
|
||||
4. Paste the initial Setup URI, enter its passphrase, and select `Test Settings and Continue`.
|
||||
|
||||
|
||||
|
||||
5. Select `Restart and Initialise Server`, then read and accept the final overwrite confirmation only when this Vault is the intended source of truth.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -64,7 +64,7 @@ Generate a fresh Setup URI from the working first device:
|
||||
1. Run `Self-hosted LiveSync: Copy settings as a new Setup URI` from the command palette.
|
||||
2. Enter a new Setup URI passphrase.
|
||||
|
||||
|
||||
|
||||
|
||||
3. Copy the resulting URI.
|
||||
|
||||
@@ -80,7 +80,7 @@ Start with a new or separately backed-up Vault.
|
||||
2. Open onboarding, select `I am adding a device to an existing synchronisation setup`, and choose the recommended Setup URI method.
|
||||
3. Enter the URI generated by the first device and its passphrase.
|
||||
|
||||
|
||||
|
||||
|
||||
4. Select `Restart and Fetch Data`.
|
||||
|
||||
@@ -96,7 +96,7 @@ Start with a new or separately backed-up Vault.
|
||||
|
||||
Confirm that the first device's test note appears unchanged. Create a second ordinary note on the new device, wait for its journal synchronisation to finish, and confirm that it reaches the first device. Configure optional features only after this two-way check passes.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -104,5 +104,5 @@ Confirm that the first device's test note appears unchanged. Create a second ord
|
||||
|
||||
- Treat the endpoint, bucket, prefix, access key, secret key, Vault passphrase, Setup URI, and Setup URI passphrase as sensitive.
|
||||
- Use a distinct prefix per synchronisation set unless shared data is explicitly intended.
|
||||
- Do not select first-device initialisation against an existing prefix unless replacing its contents is deliberate.
|
||||
- Do not initialise the first device against an existing prefix unless replacing its contents is deliberate.
|
||||
- Object Storage is not a Vault backup. Keep independent backups and test restoration separately.
|
||||
|
||||
@@ -167,7 +167,7 @@ Now `https://tiles-photograph-routine-groundwater.trycloudflare.com` is our serv
|
||||
|
||||
## 4. Client Setup
|
||||
> [!TIP]
|
||||
> 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.
|
||||
> A generated Setup URI is the recommended path because it carries the current defaults for a new Vault and the selected 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
|
||||
@@ -185,7 +185,7 @@ deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.co
|
||||
>
|
||||
> If `uri_passphrase` is omitted, the generator creates a cryptographically random value and prints it once.
|
||||
|
||||
The generator consumes the exact registry-pinned Commonlib release used by the provisioning utility. It creates a configured CouchDB remote profile, applies the current new-Vault defaults, and encodes them with Commonlib's Setup URI contract.
|
||||
The generator consumes the exact registry-pinned Commonlib release used by the provisioning utility. It creates a configured CouchDB remote profile, applies the current defaults for a new Vault, and encodes them with Commonlib's Setup URI contract.
|
||||
|
||||
You will then get the following output:
|
||||
|
||||
@@ -202,7 +202,7 @@ Store the Setup URI and its passphrase separately.
|
||||
|
||||
Follow [Quick setup](./quick_setup.md#set-up-the-first-device) for the first device. It covers the current onboarding Notice, Setup URI import, server initialisation, and the safety prompts shown for a newly provisioned database.
|
||||
|
||||
After ordinary note synchronisation works, [generate a new Setup URI on that first device](./quick_setup.md#create-a-setup-uri-for-another-device), then follow [Add another device](./quick_setup.md#add-another-device). Do not make the second device depend on retaining the provisioning-time bootstrap URI. Configure optional features only after the normal path is verified; [Hidden File Sync has its own guide](./tips/hidden-file-sync.md).
|
||||
After ordinary note synchronisation works, [generate a new Setup URI on that first device](./quick_setup.md#create-a-setup-uri-for-another-device), then follow [Add another device](./quick_setup.md#add-another-device). Do not make the second device depend on retaining the initial Setup URI produced during provisioning. Configure optional features only after the normal path is verified; [Hidden File Sync has its own guide](./tips/hidden-file-sync.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
+7
-7
@@ -47,7 +47,7 @@ On the working first device:
|
||||
1. Run `Self-hosted LiveSync: Copy settings as a new Setup URI` from the command palette.
|
||||
2. Enter a new Setup URI passphrase.
|
||||
|
||||
|
||||
|
||||
|
||||
3. Copy the resulting URI.
|
||||
|
||||
@@ -61,7 +61,7 @@ Keep the first device online. Store the new URI and its passphrase separately.
|
||||
2. Open onboarding, select `I am adding a device to an existing synchronisation setup`, and choose the recommended Setup URI method.
|
||||
3. Enter the Setup URI generated by the first device and its passphrase.
|
||||
|
||||
|
||||
|
||||
|
||||
4. Select `Restart and Fetch Data`.
|
||||
|
||||
@@ -73,7 +73,7 @@ Keep the first device online. Store the new URI and its passphrase separately.
|
||||
|
||||
|
||||
|
||||
6. In `P2P Rebuild`, confirm that the expected first-device name is shown, then select `Sync`.
|
||||
6. In `P2P Rebuild`, confirm that the expected name of the first device is shown, then select `Sync`.
|
||||
|
||||
|
||||
|
||||
@@ -83,16 +83,16 @@ Keep the first device online. Store the new URI and its passphrase separately.
|
||||
|
||||
8. Keep both devices open until the test note appears on the second device.
|
||||
|
||||
|
||||
|
||||
|
||||
## Verify the return journey
|
||||
|
||||
Create a second ordinary note on the second device. Keep automatic announcements disabled and prove the next finite synchronisation explicitly:
|
||||
Create a second ordinary note on the second device. Keep automatic announcements disabled, then run and verify the next synchronisation explicitly:
|
||||
|
||||
1. Open `P2P Status` on both devices.
|
||||
2. If a peer no longer appears, select `Disconnect` and then `Open connection` on the first device, followed by the second device. The device which joins last is advertised to devices which are already in the room.
|
||||
3. On the first device, select `Refresh`, verify the second-device name, then select `Replicate now`.
|
||||
4. On the second device, verify the requesting first-device name and select `Accept` or `Accept Temporarily`.
|
||||
4. On the second device, verify the name of the requesting first device and select `Accept` or `Accept Temporarily`.
|
||||
|
||||
|
||||
|
||||
@@ -119,7 +119,7 @@ An announcement contains no Vault data and does not transfer a change by itself.
|
||||
- Check signalling relay reachability separately from WebRTC connectivity.
|
||||
- Review VPN and TURN options in [Peer-to-Peer Synchronisation Tips](./tips/p2p-sync-tips.md).
|
||||
|
||||
## Controlled or self-hosted bootstrap
|
||||
## Controlled or self-hosted setup
|
||||
|
||||
The ordinary route above starts in the plug-in UI and can use the project's public signalling relay. For a controlled deployment, prepare your own Nostr-compatible relay and enter it in `Signalling relay URLs` on every device.
|
||||
|
||||
|
||||
@@ -52,7 +52,7 @@ If the device was asleep, Obsidian was in the background, or the peer disconnect
|
||||
|
||||
## Mobile limitations
|
||||
|
||||
Keep Obsidian visible and the device awake during initial transfer, rebuild, or a large finite synchronisation. Wake Lock support is best effort and cannot prevent the operating system from suspending or terminating a background application.
|
||||
Keep Obsidian visible and the device awake during initial transfer, rebuild, or a large synchronisation. Wake Lock support is best effort and cannot prevent the operating system from suspending or terminating a background application.
|
||||
|
||||
## Collect evidence
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@ If the log reports missing chunks or a size mismatch:
|
||||
2. on a device which has the correct file, run `Recreate missing chunks for all files`, then synchronise; and
|
||||
3. if the mismatch remains, run `Verify and repair all files` from `Hatch` and review which copy is authoritative.
|
||||
|
||||
## A configuration-mismatch dialogue blocks synchronisation
|
||||
## A configuration mismatch dialogue blocks synchronisation
|
||||
|
||||
Some settings must match across devices. LiveSync pauses synchronisation when the local and remote values differ rather than propagating an unexpected change silently.
|
||||
|
||||
@@ -153,4 +153,4 @@ Follow [Recovery and flag files](recovery.md). A `redflag.md` emergency stop rem
|
||||
|
||||
## Further technical context
|
||||
|
||||
See [Technical Information](tech_info.md) for database and synchronisation internals. Current behaviour belongs in this guide; older defect-specific instructions remain in the release histories.
|
||||
See [Technical Information](tech_info.md) for database and synchronisation internals. Current behaviour belongs in this guide; instructions for older defects remain in the release histories.
|
||||
|
||||
Reference in New Issue
Block a user