docs: add Journal definition and refine Object Storage setup guidance

Add an entry for Journal / Journal Sync to the project glossary under user-facing terms.

Update README.md table typography for WebRTC Peer-to-Peer.

In docs/setup_object_storage.md, add early navigation to manual setup, document CORS bypass via 'Use internal API', and align troubleshooting steps.
This commit is contained in:
vorotamoroz committed 2026-11-06 02:33:00 +00:00
1 parent 0942d461cf
commit a1e2120a8b
3 files changed
+13 -3

No files matched your search

+1 -1
View File
@@ -50,7 +50,7 @@ Choose **CouchDB** or **Object Storage** for central storage, or use **WebRTC Pe
| **CouchDB (Self-hosted)**<br>*(Own VPS, NAS, Docker, or Raspberry Pi)* | ✅ Full | ✅ Yes | ⚠️ Requires HTTPS (public or private endpoint)[^private-https] | High (manage OS, Docker, and backups) | Free (on existing hardware) | Users with home servers or private infrastructure | | **CouchDB (Self-hosted)**<br>*(Own VPS, NAS, Docker, or Raspberry Pi)* | ✅ Full | ✅ Yes | ⚠️ Requires HTTPS (public or private endpoint)[^private-https] | High (manage OS, Docker, and backups) | Free (on existing hardware) | Users with home servers or private infrastructure |
| **CouchDB (Fly.io)**<br>*(Cloud container PaaS)* | ✅ Full | ✅ Yes | ✅ Out of the box (HTTPS included) | Low (scripted setup via notebook) | ~USD 2.34 / mo in Ashburn[^fly-pricing]<br>*(see [cost details](docs/setup_flyio.md#costs-before-deployment))* | Users wanting real-time sync without managing hardware | | **CouchDB (Fly.io)**<br>*(Cloud container PaaS)* | ✅ Full | ✅ Yes | ✅ Out of the box (HTTPS included) | Low (scripted setup via notebook) | ~USD 2.34 / mo in Ashburn[^fly-pricing]<br>*(see [cost details](docs/setup_flyio.md#costs-before-deployment))* | Users wanting real-time sync without managing hardware |
| **Object Storage (S3 / R2)**<br>*(Cloudflare R2, AWS S3, or MinIO)* | ❌ Periodic or on-save only | ✅ Yes | Managed services: HTTPS included<br>Self-hosted: configure HTTPS | Managed services: bucket configuration<br>Self-hosted: manage the server and backups | USD 0.00 within R2 free allowances[^r2-pricing]<br>*(see [cost guide](docs/setup_object_storage_costs.md))* | Users who prefer Object Storage without server maintenance | | **Object Storage (S3 / R2)**<br>*(Cloudflare R2, AWS S3, or MinIO)* | ❌ Periodic or on-save only | ✅ Yes | Managed services: HTTPS included<br>Self-hosted: configure HTTPS | Managed services: bucket configuration<br>Self-hosted: manage the server and backups | USD 0.00 within R2 free allowances[^r2-pricing]<br>*(see [cost guide](docs/setup_object_storage_costs.md))* | Users who prefer Object Storage without server maintenance |
| **WebRTC Peer-to-Peer**<br>*(Direct device-to-device)* | ✅ Full *(while connected)* | ❌ Both devices must be online | ⚠️ Limited by OS background tasks | None (free public signalling relay) | Completely Free | Users who prefer no central storage server | | **WebRTC Peer-to-Peer**<br>*(Direct device-to-device)* | ✅ Full *(while connected)* | ❌ Both devices must be online | ⚠️ Limited by OS background tasks | None (free public signalling relay) | Free (no server required) | Users who prefer no central storage server |
> [!NOTE] > [!NOTE]
> **How Object Storage request counts affect costs**: > **How Object Storage request counts affect costs**:
+6
View File
@@ -102,6 +102,12 @@ recovery guidance, or diagnostics intended for users.
CouchDB or Object Storage remote, with the current device first. Records CouchDB or Object Storage remote, with the current device first. Records
describe participation, not current online activity. **Forget device** removes describe participation, not current online activity. **Forget device** removes
an obsolete device record; it does not delete Vault files or revoke credentials. an obsolete device record; it does not delete Vault files or revoke credentials.
- **Journal / Journal Sync:** The synchronisation mechanism used with
S3-compatible Object Storage and non-database remotes. Rather than
transferring individual files directly, Self-hosted LiveSync groups database
changes (Metadata documents and content Chunks) into compressed, time-stamped
journal packages. Devices track their synchronisation sequence using markers
and exchange only missing packages.
- **JWT Authentication:** An experimental CouchDB authentication option which - **JWT Authentication:** An experimental CouchDB authentication option which
uses a JSON Web Token instead of standard credentials. It requires a private uses a JSON Web Token instead of standard credentials. It requires a private
key or secret, algorithm, expiry duration, subject, and key ID. key or secret, algorithm, expiry duration, subject, and key ID.
+6 -2
View File
@@ -14,7 +14,7 @@ Prepare the following:
- an access key and secret key with access to the selected bucket; - an access key and secret key with access to the selected bucket;
- a bucket name and region; - a bucket name and region;
- a unique bucket prefix when the bucket is shared or reserved for this Vault; - a unique bucket prefix when the bucket is shared or reserved for this Vault;
- CORS configuration permitting Obsidian's web origins (`app://obsidian.md`, `capacitor://localhost`, `http://localhost`) with `ETag` exposed; and - CORS configuration permitting Obsidian's web origins (`app://obsidian.md`, `capacitor://localhost`, `http://localhost`) with `ETag` exposed (or enable `Use internal API` during setup to bypass CORS restrictions); and
- separate passphrases for Vault encryption and Setup URI encryption. - separate passphrases for Vault encryption and Setup URI encryption.
Back up every Vault involved, and do not use Obsidian Sync, iCloud synchronisation, or another synchronisation service on the same Vault. Back up every Vault involved, and do not use Obsidian Sync, iCloud synchronisation, or another synchronisation service on the same Vault.
@@ -32,9 +32,13 @@ Match your storage service credentials to the plug-in setup fields:
| Region specified by the provider (e.g., `auto` for R2) | `Region` | `region` | | Region specified by the provider (e.g., `auto` for R2) | `Region` | `region` |
| Folder prefix reserved for this Vault, such as `my-vault/` | `Folder Prefix` | `bucket_prefix` | | Folder prefix reserved for this Vault, such as `my-vault/` | `Folder Prefix` | `bucket_prefix` |
| Path-style addressing (required by some servers like MinIO) | `Use Path-Style Access` | `force_path_style` | | Path-style addressing (required by some servers like MinIO) | `Use Path-Style Access` | `force_path_style` |
| Bypass CORS via Obsidian's native request API | `Use internal API` | `use_custom_request_handler` |
## Generate the initial Setup URI ## Generate the initial Setup URI
> [!TIP]
> If you prefer to configure settings directly in Obsidian rather than using the command-line Setup URI generator, see [Configure the first device manually](#configure-the-first-device-manually).
The public generator applies the Object Storage preset and records the connection as the selected remote profile. Run it from a trusted terminal: The public generator applies the Object Storage preset and records the connection as the selected remote profile. Run it from a trusted terminal:
```sh ```sh
@@ -131,7 +135,7 @@ If you prefer to configure settings directly in Obsidian rather than using the D
3. Configure `End-to-End Encryption` and enter a strong Vault encryption passphrase. Save this passphrase securely. 3. Configure `End-to-End Encryption` and enter a strong Vault encryption passphrase. Save this passphrase securely.
4. Select the S3-compatible Object Storage option and proceed to `S3/MinIO/R2 Configuration`. 4. Select the S3-compatible Object Storage option and proceed to `S3/MinIO/R2 Configuration`.
5. Enter your bucket settings using the [Setting fields reference](#setting-fields-reference) table above. 5. Enter your bucket settings using the [Setting fields reference](#setting-fields-reference) table above.
6. Select `Test Settings and Continue`. If the connection test fails, verify the API endpoint, credentials, bucket permissions, region, and CORS configuration. 6. Select `Test Settings and Continue`. If the connection test fails, verify the API endpoint, credentials, bucket permissions, and region. If CORS blocks the request or cannot be configured on your bucket, enable `Use internal API` to route requests through Obsidian's native HTTP handler.
7. Proceed to `Restart and Initialise Server`, then complete the confirmation steps as described in [Set up the first device](#set-up-the-first-device). 7. Proceed to `Restart and Initialise Server`, then complete the confirmation steps as described in [Set up the first device](#set-up-the-first-device).
8. Once your test note synchronises, follow [Generate the second-device Setup URI](#generate-the-second-device-setup-uri) to connect subsequent devices easily. 8. Once your test note synchronises, follow [Generate the second-device Setup URI](#generate-the-second-device-setup-uri) to connect subsequent devices easily.