2f92dc4c1f
Add documentation of the monorepo layout, describing the `docmost-client` and `sync` packages and their responsibilities. Clarify that all Docmost access is performed via REST for reads, while writes use collab/Yjs, documenting the architectural decision and its rationale.
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.
Status: scaffold only — the sync engine is not implemented yet.
src/index.tsvalidates configuration and exits. The engine described inSPEC.mdis 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), 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
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
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.