ef223e13ff
Set up the project structure per the new-project guide, adapted from the Python skeleton to the Node/TS stack fixed in SPEC.md (reuses docmost-mcp). Scaffold only — the sync engine is not implemented yet. - src/settings.ts: single config layer on zod, schema keyed by real ENV names; credentials and own-service address have no default (fail fast). - src/config-errors.ts: loadSettingsOrExit — clear startup message naming the missing/invalid env var instead of a raw stack trace; exit(1). - src/index.ts: thin entry point that validates config and logs (stub). - test/: vitest unit tests for settings parsing and config errors (10 tests). - Makefile (install/env/build/test/run/dev/clean), strict tsconfig, vitest. - Dockerfile (single-stage, no EXPOSE, prunes dev deps), docker-compose (daemon, volume on /app/data, watchtower), ghcr CI with build needs test. - .env.example, .gitignore/.dockerignore, AGENTS.md, README.md. - Pinned deps (dotenv, zod) + committed package-lock.json.
54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# 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.
|