From 32d64262f8a5bd5dc1e9ee255b399197ce31bbc1 Mon Sep 17 00:00:00 2001
From: Bojay Liu <189326887+BojayL@users.noreply.github.com>
Date: Sat, 20 Jun 2026 00:24:52 +0800
Subject: [PATCH] Add compose services for local stack

---
 Dockerfile.api                    |  2 +-
 Dockerfile.gateway                |  2 +-
 README.md                         | 10 +++++++
 docker-compose.yml                | 44 +++++++++++++++++++++++++++++++
 docs/deployment/docker-compose.md | 29 +++++++++++++++++---
 migrations/001_init.sql           |  2 +-
 6 files changed, 82 insertions(+), 7 deletions(-)

diff --git a/Dockerfile.api b/Dockerfile.api
index ce4f0f0..d69cbad 100644
--- a/Dockerfile.api
+++ b/Dockerfile.api
@@ -8,7 +8,7 @@ COPY migrations ./migrations
 RUN cargo build --release -p waveflow-api
 
 FROM debian:bookworm-slim
-RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY --from=builder /app/target/release/waveflow-api /usr/local/bin/waveflow-api
 COPY migrations /app/migrations
diff --git a/Dockerfile.gateway b/Dockerfile.gateway
index 698684d..63d8bfb 100644
--- a/Dockerfile.gateway
+++ b/Dockerfile.gateway
@@ -8,7 +8,7 @@ COPY migrations ./migrations
 RUN cargo build --release -p waveflow-gateway
 
 FROM debian:bookworm-slim
-RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y ca-certificates curl && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY --from=builder /app/target/release/waveflow-gateway /usr/local/bin/waveflow-gateway
 COPY migrations /app/migrations
diff --git a/README.md b/README.md
index 351345e..543a698 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,16 @@ GitHub PR merge → Gateway (webhook + HMAC) → Soroban Escrow → Contributor
 ```bash
 cp .env.example .env
 docker-compose up -d
+curl http://localhost:8080/health
+curl http://localhost:8081/health
+```
+
+The compose stack starts Postgres, the GitHub webhook gateway on port `8080`, and the REST API on port `8081`. Both Rust services run migrations during startup.
+
+For host-based development, start only the database and run the services with Cargo:
+
+```bash
+docker-compose up -d postgres
 cargo build --workspace
 cargo test --workspace
 ```
diff --git a/docker-compose.yml b/docker-compose.yml
index 7f1e86a..f7b7e7d 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -17,5 +17,49 @@ services:
       timeout: 5s
       retries: 5
 
+  waveflow-gateway:
+    build:
+      context: .
+      dockerfile: Dockerfile.gateway
+    container_name: waveflow-gateway
+    env_file:
+      - .env
+    environment:
+      DATABASE_URL: postgres://waveflow:waveflow@postgres:5432/waveflow
+      GATEWAY_PORT: "8080"
+      PORT: "8080"
+    ports:
+      - "8080:8080"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/health >/dev/null"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  waveflow-api:
+    build:
+      context: .
+      dockerfile: Dockerfile.api
+    container_name: waveflow-api
+    env_file:
+      - .env
+    environment:
+      DATABASE_URL: postgres://waveflow:waveflow@postgres:5432/waveflow
+      API_PORT: "8081"
+      PORT: "8081"
+    ports:
+      - "8081:8081"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8081/health >/dev/null"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
 volumes:
   postgres-data:
diff --git a/docs/deployment/docker-compose.md b/docs/deployment/docker-compose.md
index 6aab8e7..4d31afc 100644
--- a/docs/deployment/docker-compose.md
+++ b/docs/deployment/docker-compose.md
@@ -4,7 +4,7 @@ File: `docker-compose.yml`
 
 ## Purpose
 
-Provides local Postgres for API and gateway development. Rust binaries run on the host via `cargo run`.
+Provides a local WaveFlow stack with Postgres, the GitHub webhook gateway, and the REST API.
 
 ## Start
 
@@ -12,6 +12,15 @@ Provides local Postgres for API and gateway development. Rust binaries run on th
 docker-compose up -d
 ```
 
+The gateway is exposed at `http://localhost:8080`, and the API is exposed at `http://localhost:8081`.
+
+Health checks:
+
+```bash
+curl http://localhost:8080/health
+curl http://localhost:8081/health
+```
+
 ## Connection string
 
 From `.env.example`:
@@ -24,11 +33,23 @@ Host port `5433` avoids conflicts with other local Postgres instances on 5432.
 
 ## Services
 
-Typically a single `postgres` service with volume for data persistence. Check `docker-compose.yml` for the current image tag and credentials.
+| Service | Purpose | Host port |
+|---------|---------|-----------|
+| `postgres` | Local Postgres database with persisted volume | `5433` |
+| `waveflow-gateway` | GitHub webhook gateway | `8080` |
+| `waveflow-api` | REST API | `8081` |
 
-## With Rust services
+The Rust services load `.env`, override `DATABASE_URL` for the compose network, wait for a healthy Postgres container, and run SQLx migrations during startup.
 
-Compose does not start gateway/API containers by default. Use Render Dockerfiles (`Dockerfile.gateway`, `Dockerfile.api`) as reference for production image builds.
+## Host-based Rust services
+
+For faster edit-compile cycles, start only Postgres and run the services on the host:
+
+```bash
+docker-compose up -d postgres
+cargo run -p waveflow-gateway
+cargo run -p waveflow-api
+```
 
 ## Stop and reset
 
diff --git a/migrations/001_init.sql b/migrations/001_init.sql
index f911ccd..1d2f171 100644
--- a/migrations/001_init.sql
+++ b/migrations/001_init.sql
@@ -1,4 +1,4 @@
-# Initial Postgres schema for WaveFlow programs, contributors, payouts, and webhook audit.
+-- Initial Postgres schema for WaveFlow programs, contributors, payouts, and webhook audit.
 -- WaveFlow migration 001: core tables
 
 CREATE TABLE IF NOT EXISTS programs (