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:
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#
- Apply migrations first, as a single-runner step (not on app boot — the
server expects the schema present):Migrations are backwards-compatible (expand→migrate→contract), so this is safe to run before the new image is live. See the migration strategy.bash
DATABASE_URL=… pnpm --filter @demeter/api db:migrate - Roll out the new image. Old and new instances run concurrently during the rollout; backwards-compatible migrations make this safe.
- 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/healthand readiness/ load-balancer probe to/health/ready.
Local development#
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:
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.