# Deployment

## Requirements

- Node.js 22 or newer
- npm 10 or newer

## Install

```bash
npm install
```

## Build

```bash
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

```bash
npm run dev:server
```

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

## Run With Docker

Use Docker Compose from the repository root:

```bash
docker compose up --build sync-server
```

Or build the image directly:

```bash
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`.