Eve Local Dev Loop (Docker Compose)

Use this skill to run and test the app locally with Docker Compose, then hand off to Eve for staging deploys.

Preconditions

• A compose.yaml or docker-compose.yml exists in the repo.
• The Eve manifest (.eve/manifest.yaml) reflects the same services and ports.

Local Run

# Start local services (DB + migrations)
docker compose up -d

# Start API in dev mode (hot reload)
cd apps/api && npm run dev

# Start web in dev mode (Vite dev server with /api proxy)
cd apps/web && npm run dev

# View DB logs
docker compose logs -f

# Reset DB (drop + recreate + migrate)
docker compose down -v && docker compose up -d

Recommended docker-compose.yml

Use the Eve-migrate image locally for migration parity with staging:

services:
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: myapp
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d myapp"]
      interval: 5s
      timeout: 5s
      retries: 5

  migrate:
    image: ghcr.io/incept5/eve-migrate:latest
    environment:
      DATABASE_URL: postgres://app:app@db:5432/myapp
    volumes:
      - ./db/migrations:/migrations:ro
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

Why eve-migrate? The same runner executes in both local and staging, giving migration parity. It tracks applied migrations in schema_migrations (idempotent, checksummed, transactional). Plain SQL files with timestamp prefixes: 20260312000000_initial_schema.sql.

Run migrations manually after adding a new file:

docker compose run --rm migrate

Keep Compose and Manifest in Sync

• Match service names and exposed ports between Compose and the Eve manifest.
• The Compose db service mirrors the manifest's managed DB. Locally it's a container; in staging, Eve provisions it.
• The Compose migrate service mirrors the manifest's migrate job. Both use eve-migrate and mount db/migrations/.
• If a service is public in production, set x-eve.ingress.public: true in the manifest.
• Use ${secret.KEY} in the manifest and keep local values in .eve/dev-secrets.yaml.

Local Environment Variables

• Create .env for the API (e.g., DATABASE_URL=postgresql://app:app@localhost:5432/myapp).
• Prefer .env for Compose and .eve/dev-secrets.yaml for manifest interpolation.
• Never commit secrets; keep .eve/dev-secrets.yaml in .gitignore.
• For the Vite dev server, configure a proxy in vite.config.ts to forward /api to http://localhost:3000 (matching the nginx proxy pattern in production).

Promote to Staging

# Ensure profile and auth are set
eve profile use staging
eve auth status

# Set required secrets
eve secrets set API_KEY "value" --project proj_xxx

# Deploy to staging (requires --ref with 40-char SHA or a ref resolved against --repo-dir)
eve env deploy staging --ref main --repo-dir .

# If the environment has a pipeline configured, this triggers the pipeline.
# Use --direct to bypass pipeline and deploy directly:
eve env deploy staging --ref main --repo-dir . --direct

Track the deploy job:

eve job list --phase active
eve job follow <job-id>
eve job result <job-id>

If Local Works but Staging Fails

• Re-check manifest parity with Compose.
• Verify secrets exist in Eve (eve secrets list).
• Use eve job diagnose <job-id> for failure details.