# Demeter Deployment Procedures

This document describes how to **build, configure, and run** the Demeter
artifacts (API, web, mobile). It is grounded in the artifacts that exist in the
repo today. Cloud-target _provisioning_ (AWS ECS/RDS/CloudFront/etc.) is tracked
separately under TODOS §29.19 and is intentionally out of scope here — those are
infrastructure controls that depend on an account and a deploy target.

## API (`apps/demeter/api`)

### Build

A multi-stage production image is defined at `apps/demeter/api/Dockerfile`:

```bash
docker build -f apps/demeter/api/Dockerfile -t oshun/demeter-api:latest .
```

(For a non-container build: `pnpm --filter @demeter/api build` → `dist/`, run
with `node dist/server.js`.)

### Required runtime configuration

The server validates its environment at boot via `src/config.ts` (Zod). Key
variables:

| Variable                                           | Purpose                                         |
| -------------------------------------------------- | ----------------------------------------------- |
| `NODE_ENV`                                         | `production` in deployed environments           |
| `HOST` / `PORT`                                    | Bind address / port (image exposes `3030`)      |
| `DATABASE_URL`                                     | PostgreSQL connection string                    |
| `DB_POOL_MIN` / `DB_POOL_MAX`                      | Connection-pool sizing (min ≤ max, validated)   |
| `REDIS_URL`                                        | Redis (rate-limit / cache)                      |
| `JWT_SECRET` / `JWT_ISSUER`                        | Access-token signing                            |
| `MAGIC_LINK_SECRET`                                | Passwordless-link signing                       |
| `CORS_ORIGIN`                                      | Allowed web origin(s)                           |
| `RATE_LIMIT_ENABLED`                               | Per-user rate limiting (default on)             |
| `OAUTH_GOOGLE_CLIENT_ID` / `OAUTH_APPLE_CLIENT_ID` | OAuth verification                              |
| `WEATHER_API_KEY`                                  | Weather provider (if the source requires a key) |
| `IOT_API_KEY`                                      | IoT ingestion key                               |
| `LOG_LEVEL`                                        | Pino log level                                  |

### Release sequence

1. **Apply migrations first**, as a single-runner step (not on app boot — the
   server expects the schema present):
   ```bash
   DATABASE_URL=… pnpm --filter @demeter/api db:migrate
   ```
   Migrations are backwards-compatible (expand→migrate→contract), so this is
   safe to run before the new image is live. See the
   [migration strategy](migration-strategy.md).
2. **Roll out** the new image. Old and new instances run concurrently during the
   rollout; backwards-compatible migrations make this safe.
3. **Verify** via the probes (below). Roll back a bad deploy by redeploying the
   prior image — no schema change needed.

### Health probes

- `GET /health` — liveness (200 `{ status: "ok" }`).
- `GET /health/ready` — readiness; reports per-dependency status (Postgres,
  Redis). Wire your orchestrator's liveness probe to `/health` and readiness/
  load-balancer probe to `/health/ready`.

## Local development

```bash
docker compose -f docker/docker-compose.dev.yml up -d   # Postgres, Redis, etc.
pnpm install
pnpm --filter @demeter/api db:migrate
pnpm --filter @demeter/api dev                          # tsx --watch
```

## Web (`apps/demeter/web`)

`pnpm --filter <web> build` produces a static Vite bundle suitable for any
static host / CDN. Configure the API base URL via the web app's env at build
time.

## Mobile (`apps/demeter/mobile`)

Builds are driven by **EAS** (`eas.json`) with `development` / `preview` /
`production` profiles for iOS and Android:

```bash
eas build --profile production --platform ios       # or android
eas submit --profile production --platform ios       # store submission
```

`production` uses store distribution + `autoIncrement`; `preview`/`development`
use internal distribution. Store-listing creation and review submission are
manual, account-bound steps (§29.19.6).

## Cloud provisioning (deferred)

AWS ECS task definitions/services/autoscaling, RDS, ElastiCache, CloudFront,
Route53/ACM, CloudWatch/X-Ray, SES/SNS, and store-account setup are deployment-
infrastructure controls tracked under §29.19. They require an account and a
chosen target and are not part of the locally-buildable artifact set above.
