Get the Demeter API, web, and mobile apps running locally.
Prerequisites#
- Node.js (see the API Dockerfile's
NODE_VERSIONfor the supported major) + pnpm (via Corepack). - Docker (for Postgres, Redis, and friends).
1. Infrastructure#
docker compose -f docker/docker-compose.dev.yml up -d # Postgres, Redis, MinIO, Mailpit
docker compose -f docker/docker-compose.dev.yml ps # verify health
Demeter uses the domain-isolated demeter database (and demeter_test for
integration tests). Connection URLs live in the root .env.
2. Install & migrate#
pnpm install
pnpm --filter @demeter/api db:migrate # apply Drizzle migrations to `demeter`
3. Run the apps#
pnpm --filter @demeter/api dev # Fastify API (tsx --watch), :3030
pnpm --filter <demeter-web> dev # Vite dev server
# mobile: start Expo from apps/demeter/mobile (see its README)
Health check: curl localhost:3030/health → { "status": "ok" }. Interactive
API docs: http://localhost:3030/docs.
4. Environment#
The API validates its env at boot (src/config.ts). For local dev the defaults
in the root .env suffice; the variables that matter are DATABASE_URL,
REDIS_URL, JWT_SECRET, MAGIC_LINK_SECRET, and the pool/rate-limit knobs —
see the
deployment doc for
the full matrix.
5. Tests#
pnpm --filter @demeter/api test # unit (vitest)
pnpm --filter @demeter/api test:integration # integration (needs demeter_test)
pnpm --filter @demeter/api test:perf # performance suite (opt-in)
See the testing guidelines for the harness and the demeter_test
reset rule.
Troubleshooting#
Common setup issues (DB unreachable, migrations not applied, integration suite skipped, mobile jest env) are covered in the troubleshooting guide.