Add compose services for local stack

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

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

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

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:

docs/deployment/docker-compose.md

@@ -4,14 +4,23 @@ 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
 
 ```bash
 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
 

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 (