98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
# Obsidian Sync
|
|
|
|
Obsidian Sync is a self-hosted, end-to-end encrypted vault sync system for Obsidian across Windows, Linux, and Android. It consists of an Obsidian plugin, a sync server, and shared protocol and crypto packages inside a TypeScript monorepo.
|
|
|
|
## Features
|
|
|
|
- End-to-end encrypted text note and binary attachment sync
|
|
- Automatic text merge with conflict markers when both sides change
|
|
- Binary conflict copies when attachments diverge
|
|
- Durable server state stored on disk
|
|
- Structured JSON-line diagnostics and client sync log upload
|
|
- Recovery bundle export and import for onboarding new devices
|
|
- Device listing and revocation
|
|
- Vault key rotation with recovery-bundle refresh
|
|
- Paged pull and batched push behavior so interrupted sync runs can resume safely
|
|
|
|
## Repository Layout
|
|
|
|
- `apps/obsidian-plugin`: Obsidian plugin entry point, settings UI, and sync orchestration
|
|
- `apps/sync-server`: Express server for encrypted revision exchange and device management
|
|
- `packages/sync-protocol`: Shared request and response schemas
|
|
- `packages/sync-engine`: Shared crypto, hashing, and merge helpers
|
|
- `docs`: Architecture and deployment notes
|
|
- `tests`: Focused contract and store-level integration tests
|
|
|
|
## Requirements
|
|
|
|
- Node.js 22 or newer
|
|
- npm 10 or newer
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Build
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
## Test
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
## Run The Server
|
|
|
|
```bash
|
|
npm run dev:server
|
|
```
|
|
|
|
The default server URL is `http://localhost:8787`.
|
|
|
|
## First-Time Setup
|
|
|
|
1. Start the sync server.
|
|
2. Load the plugin into an Obsidian vault.
|
|
3. Set the server URL, vault ID, and device name in the plugin settings.
|
|
4. Run a manual sync to register the first device and generate the initial vault key.
|
|
5. Export a recovery bundle from the settings tab and store it securely.
|
|
|
|
## Add Another Device
|
|
|
|
1. Install the plugin on the second device.
|
|
2. Open the plugin settings and paste the recovery bundle into the import field.
|
|
3. Run a manual sync to register that device and pull the encrypted vault contents.
|
|
|
|
## Rotate The Vault Key
|
|
|
|
1. Open the plugin settings and use `Rotate key`.
|
|
2. Wait for the client to re-encrypt and upload the current vault contents.
|
|
3. Export the fresh recovery bundle.
|
|
4. Import that new bundle on every other device before the next sync.
|
|
|
|
## Revoke A Device
|
|
|
|
Use the plugin settings device list to revoke a device that should no longer have access. A revoked device can no longer authenticate to the server.
|
|
|
|
## Server Data
|
|
|
|
- `data/sync-state.json`: durable revision, device, tombstone, and key-status state
|
|
- `data/logs/server.jsonl`: structured server and client-sync diagnostics
|
|
|
|
## Current Limitations
|
|
|
|
- The server storage backend is file-based rather than SQLite or PostgreSQL.
|
|
- Sync validation is focused on shared libraries and the server store; there is not yet a full Obsidian plugin integration harness.
|
|
- Device onboarding is driven by a copy-and-paste recovery bundle instead of a richer pairing flow.
|
|
|
|
## Documentation
|
|
|
|
- `docs/architecture.md`
|
|
- `docs/deployment.md`
|
|
- `Plan.md`
|