# docmost-sync

Bidirectional sync between Docmost articles and a local Markdown git vault — the
git repository is the state store. For the full design and the phased
implementation plan, see [`SPEC.md`](./SPEC.md).

> **Status: scaffold only — the sync engine is not implemented yet.**
> `src/index.ts` validates configuration and exits. The engine described in
> `SPEC.md` is out of scope for this scaffold.

It reuses the sibling project **docmost-mcp** as a library (DocmostClient,
ProseMirror ↔ Markdown converter, collab-write).

## Configuration

All config comes from ENV / `.env` (see [`.env.example`](./.env.example)), read
through the single settings layer in `src/settings.ts`. A missing required
variable fails at startup with a clear message that names it.

| Variable           | Required | Default      | Meaning                                                        |
| ------------------ | :------: | ------------ | -------------------------------------------------------------- |
| `DOCMOST_API_URL`  |   yes    | —            | Base URL of our Docmost instance (used for `/auth/login`).     |
| `DOCMOST_EMAIL`    |   yes    | —            | Docmost login email.                                           |
| `DOCMOST_PASSWORD` |   yes    | —            | Docmost login password.                                        |
| `DOCMOST_SPACE_ID` |   yes    | —            | The Docmost space to mirror.                                   |
| `VAULT_PATH`       |    no    | `data/vault` | Local git vault path (kept under `data/` for the volume).      |
| `GIT_REMOTE`       |    no    | _(unset)_    | Optional git remote the vault pushes to; empty = local-only.   |
| `POLL_INTERVAL_MS` |    no    | `15000`      | How often to poll Docmost for changes (ms).                    |
| `DEBOUNCE_MS`      |    no    | `2000`       | Debounce window for local file changes (ms).                   |
| `LOG_LEVEL`        |    no    | `info`       | One of `debug`, `info`, `warn`, `error`.                       |

Credentials and the address of our own Docmost instance have NO default — they
go ONLY into `.env`, never into code or inline command-line env vars.

## Quick start

```sh
make install        # install dependencies (npm ci)
make env            # create .env from .env.example, then fill it in
make test           # run the test suite (vitest)
make run            # build and run
make dev            # run in watch mode (tsx)
```

`make` (or `make help`) lists all targets.

## Deploy

Production runs a prebuilt image from `ghcr.io` (no build on prod):
`docker-compose.yml` pulls `ghcr.io/vvzvlad/docmost-sync:latest`, mounts a
volume at `/app/data`, and [watchtower](https://containrrr.dev/watchtower/)
auto-updates the container when a new image is published. CI (GitHub Actions)
builds and pushes the image; the `build` job runs only after `test` passes.