eve-local-dev-loop

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/eve-horizon/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.