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.

Run With Docker

Use Docker Compose from the repository root:

docker compose up --build sync-server

Or build the image directly:

docker build -f apps/sync-server/Dockerfile -t obsidian-sync-server .
docker run --rm -p 8787:8787 -v obsidian-sync-data:/app/data obsidian-sync-server

The compose setup binds port 8787 by default and stores durable state in a named Docker volume called obsidian-sync-data.

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.
OBSIDIAN_SYNC_PORT: optional compose override for the host port published by compose.yaml.

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.
The Docker image includes a health check against /health and stores runtime data in /app/data.

2.4 KiB Raw Blame History