Deployment

Requirements

Node.js 22 or newer
npm 10 or newer

Install

npm install

Build

npm run build

For the Obsidian client plugin, this build produces a bundled apps/obsidian-plugin/main.js beside apps/obsidian-plugin/manifest.json. Obsidian local plugins must load from that root-level main.js; dist/main.js is not used by Obsidian.

Run The Sync Server

npm run dev:server

The server listens on http://localhost:8787 by default.

Environment Variables

PORT: overrides the default HTTP port.
SYNC_DATA_DIR: overrides the default data directory. If omitted, the server writes data under ./data from the workspace root.

Data Written By The Server

data/sync-state.json: durable encrypted revision metadata, devices, tombstones, and sync history.
data/logs/server.jsonl: structured JSON-line server and client-sync diagnostics.

Management Capabilities

POST /api/devices/list: lists known devices for the vault plus active key status.
POST /api/devices/revoke: revokes a device so it can no longer authenticate.
POST /api/keys/rotate: stores the currently active vault key identifier.
POST /api/sync/pull: supports paged pulls through sinceServerRevision and limit.

Operational Notes

The server never needs plaintext note bodies. Clients encrypt before upload and decrypt after download.
Request logs include a response header named x-request-id for correlating client and server failures.
The current storage backend is file-based. It is durable for a single-node deployment but not yet designed for clustered or high-availability hosting.
The plugin updates local sync state after each accepted push batch and each applied pull page, which lets interrupted sync runs resume from the last durable checkpoint.

1.8 KiB Raw Blame History