eve-local-dev-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve Local Dev Loop (Docker Compose)

Eve本地开发流程（Docker Compose）

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

使用本技能通过Docker Compose在本地运行和测试应用，然后切换至Eve进行预发布环境部署。

Preconditions

前置条件

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

仓库中存在
```
compose.yaml
```
或
```
docker-compose.yml
```
文件。
Eve清单文件（
```
.eve/manifest.yaml
```
）中配置的服务和端口与本地配置一致。

Local Run

本地运行

bash

undefined

bash

undefined

Start local services (DB + migrations)

启动本地服务（数据库 + 迁移）

docker compose up -d

Start API in dev mode (hot reload)

以开发模式启动API（热重载）

cd apps/api && npm run dev

Start web in dev mode (Vite dev server with /api proxy)

以开发模式启动Web服务（带/api代理的Vite开发服务器）

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

undefined

docker compose down -v && docker compose up -d

undefined

Recommended docker-compose.yml

推荐的docker-compose.yml配置

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

yaml

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: public.ecr.aws/w7c4v0w3/eve-horizon/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:

bash

docker compose run --rm migrate

本地使用Eve-migrate镜像，确保与预发布环境的迁移流程一致：

yaml

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: public.ecr.aws/w7c4v0w3/eve-horizon/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

。

添加新文件后手动运行迁移：

bash

docker compose run --rm migrate

Keep Compose and Manifest in Sync

保持Compose与清单文件同步

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

确保Compose和Eve清单中的服务名称与暴露端口一致。
Compose中的
```
db
```
服务对应清单中的托管数据库：本地使用容器，预发布环境由Eve提供。
Compose中的
```
migrate
```
服务对应清单中的
```
migrate
```
任务：两者均使用eve-migrate并挂载
```
db/migrations/
```
目录。
如果服务在生产环境中公开，需在清单中设置
```
x-eve.ingress.public: true
```
。
清单中使用
```
${secret.KEY}
```
，本地值存储在
```
.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).

为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代理模式匹配）。

Promote to Staging

部署至预发布环境

bash

undefined

bash

undefined

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)

部署至预发布环境（需要--ref参数，值为40位SHA或基于--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:

使用--direct参数绕过流水线直接部署：

eve env deploy staging --ref main --repo-dir . --direct


Track the deploy job:

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

eve env deploy staging --ref main --repo-dir . --direct


跟踪部署任务：

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

重新检查清单与Compose的配置一致性。
验证Eve中是否存在所需密钥（
```
eve secrets list
```
）。
使用
```
eve job diagnose <job-id>
```
查看失败详情。