# Local Development Setup

Get the Demeter API, web, and mobile apps running locally.

## Prerequisites

- Node.js (see the API Dockerfile's `NODE_VERSION` for the supported major) +
  **pnpm** (via Corepack).
- Docker (for Postgres, Redis, and friends).

## 1. Infrastructure

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

```bash
pnpm install
pnpm --filter @demeter/api db:migrate     # apply Drizzle migrations to `demeter`
```

## 3. Run the apps

```bash
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](../operations/deployment.md#required-runtime-configuration) for
the full matrix.

## 5. Tests

```bash
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](testing.md) 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](../operations/troubleshooting.md).
