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 (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 |
| **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]
> **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
describe participation, not current online activity. **Forget device** removes
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
uses a JSON Web Token instead of standard credentials. It requires a private
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;
- a bucket name and region;
- 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.
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` |
| 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` |
| Bypass CORS via Obsidian's native request API | `Use internal API` | `use_custom_request_handler` |
## 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:
```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.
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.
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).
8. Once your test note synchronises, follow [Generate the second-device Setup URI](#generate-the-second-device-setup-uri) to connect subsequent devices easily.