From 816d2c92a018d87876a2afe77fe3b3bfb5834a9b Mon Sep 17 00:00:00 2001
From: georgeefaith <georgefaith444@gmail.com>
Date: Fri, 26 Jun 2026 23:05:36 +0000
Subject: [PATCH] docs: add Docker Compose local dev environment guide (#316)

---
 docs/docker-compose.md | 129 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 docs/docker-compose.md

diff --git a/docs/docker-compose.md b/docs/docker-compose.md
new file mode 100644
index 0000000..df30408
--- /dev/null
+++ b/docs/docker-compose.md
@@ -0,0 +1,129 @@
+# Docker Compose Local Dev Environment
+
+This guide covers running the full CosmosVote stack locally using Docker Compose.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) 24+
+- [Docker Compose](https://docs.docker.com/compose/install/) v2 (bundled with Docker Desktop)
+
+## Services
+
+| Service | Description | Port |
+|---------|-------------|------|
+| `dev` | Builder image — full Rust toolchain for development and testing | — |
+| `stellar-node` | Local Stellar node with Soroban RPC enabled | `8001:8000` |
+| `rpc-proxy` | Nginx reverse proxy in front of the Stellar RPC | `8000:8000` |
+| `artifacts` | Minimal runtime image shipping WASM artifacts only (profile: `artifacts`) | — |
+
+## Environment Variables
+
+Copy the example file and edit as needed:
+
+```bash
+cp .env.example .env
+```
+
+Key variables used by Docker Compose:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NETWORK` | `local` | Network to connect to (`local` \| `testnet` \| `mainnet`) |
+| `STELLAR_RPC_URL` | `http://stellar-node:8000` | Soroban RPC endpoint (within Compose network) |
+| `STELLAR_NETWORK_PASSPHRASE` | `Standalone Network ; February 2021` | Must match the running node |
+| `STELLAR_SECRET_KEY` | — | Admin secret key for deployment scripts |
+| `GOVERNANCE_CONTRACT_ID` | — | Populated after running `deploy.sh` |
+| `TOKEN_CONTRACT_ID` | — | Populated after running `deploy.sh` |
+
+> The `dev` service injects `STELLAR_RPC_URL` and `STELLAR_NETWORK_PASSPHRASE` automatically. You do not need to set them in `.env` for local development.
+
+## Quick Start
+
+### 1. Start the local Stellar node
+
+```bash
+docker compose up stellar-node -d
+```
+
+The node exposes the Soroban RPC at `http://localhost:8001`. The `rpc-proxy` re-exposes it at `http://localhost:8000`.
+
+### 2. Run tests inside the dev container
+
+```bash
+docker compose run --rm dev make test
+```
+
+### 3. Build WASM binaries
+
+```bash
+docker compose run --rm dev make build
+```
+
+Built WASM artifacts are written to `target/wasm32-unknown-unknown/release/` inside the mounted workspace volume.
+
+### 4. Open an interactive dev shell
+
+```bash
+docker compose run --rm dev bash
+```
+
+From inside the shell you have access to the full Rust toolchain, `stellar` CLI, `make`, and all project scripts.
+
+### 5. Build the minimal runtime (WASM artifacts only)
+
+```bash
+docker compose --profile artifacts build artifacts
+```
+
+This produces a small `debian:bookworm-slim`-based image containing only the compiled WASM files and the Stellar CLI — suitable for CI artifact storage or deployment pipelines.
+
+## Full Stack (node + dev shell)
+
+```bash
+# Bring up the Stellar node and proxy in the background
+docker compose up stellar-node rpc-proxy -d
+
+# Run the deploy script against the local node
+docker compose run --rm dev bash scripts/deploy.sh
+
+# Watch logs
+docker compose logs -f stellar-node
+```
+
+## Stopping / Cleaning Up
+
+```bash
+# Stop all services
+docker compose down
+
+# Remove volumes (clears the Stellar chain state and Cargo cache)
+docker compose down -v
+```
+
+## Ports Summary
+
+| Host port | Container port | Service |
+|-----------|---------------|---------|
+| `8000` | `8000` | `rpc-proxy` (Soroban RPC) |
+| `8001` | `8000` | `stellar-node` (direct access) |
+
+> If port `8000` is already in use on your machine, edit `docker-compose.yml` and change the host-side port mapping for `rpc-proxy`.
+
+## Troubleshooting
+
+**`stellar-node` health check fails on first start**  
+The Stellar quickstart image takes up to 30 seconds to initialize. The `dev` service waits for it automatically via `depends_on: condition: service_healthy`. If the health check never passes, check the node logs:
+
+```bash
+docker compose logs stellar-node
+```
+
+**Permission errors on the mounted workspace volume**  
+The container runs as root. If generated files (e.g., `target/`) are owned by root on the host, run:
+
+```bash
+sudo chown -R $USER:$USER target/
+```
+
+**Cargo cache not persisting between runs**  
+The `cargo-cache` and `target-cache` named volumes persist between `docker compose run` invocations. They are cleared only when you run `docker compose down -v`.