eve-local-dev-loop

Eve ローカル開発ループ（Docker Compose）

このスキルを使うと、Docker Compose でアプリをローカルで実行・テストしてから、Eve にステージングへのデプロイを引き継げます。

前提条件

• リポジトリに compose.yaml または docker-compose.yml が存在すること。
• Eve マニフェスト（.eve/manifest.yaml）が、同じサービスとポートを反映していること。

ローカルでの実行

# 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

推奨する docker-compose.yml

ステージングとのマイグレーションの同等性を保つため、ローカルでも Eve-migrate イメージを使用します。

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:

eve-migrate を使う理由: ローカルとステージングの両方で同じランナーを実行するため、マイグレーションの同等性を確保できます。適用済みのマイグレーションは schema_migrations で追跡されます（冪等性があり、チェックサムで検証され、トランザクションで実行されます）。タイムスタンプのプレフィックスが付いたプレーンな SQL ファイルを使います：20260312000000_initial_schema.sql。

新しいファイルを追加した後、マイグレーションを手動で実行します：

docker compose run --rm migrate

Compose とマニフェストを同期する

• Compose と Eve マニフェストのサービス名と公開ポートを一致させます。
• Compose の db サービスは、マニフェストで管理される DB に対応します。ローカルではコンテナーですが、ステージングでは Eve がプロビジョニングします。
• Compose の migrate サービスは、マニフェストの migrate ジョブに対応します。どちらも eve-migrate を使用し、db/migrations/ をマウントします。
• 本番環境でサービスを公開する場合は、マニフェストで x-eve.ingress.public: true を設定します。
• マニフェストでは ${secret.KEY} を使用し、ローカルの値は .eve/dev-secrets.yaml に保存します。

ローカル環境変数

• API 用に .env を作成します（例：DATABASE_URL=postgresql://app:app@localhost:5432/myapp）。
• Compose には .env を、マニフェストの値の展開には .eve/dev-secrets.yaml を使うことをおすすめします。
• シークレットをコミットしないでください。.eve/dev-secrets.yaml は .gitignore に追加したままにします。
• Vite 開発サーバーでは、vite.config.ts にプロキシを設定して /api を http://localhost:3000 に転送します（本番環境の nginx プロキシのパターンに合わせます）。

ステージングへの昇格

# 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

デプロイジョブを追跡します：

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

ローカルでは動作するが、ステージングでは失敗する場合

• マニフェストと Compose の同等性を再確認します。
• Eve にシークレットが存在することを確認します（eve secrets list）。
• 失敗の詳細を確認するには、eve job diagnose <job-id> を使います。