Eve library

Demeter Deployment Procedures

Guide

Revision 1

On this page

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.
  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.