Initial Commit

docker/README.md

@@ -0,0 +1,199 @@
+# @suaveplan/docker
+
+Docker Compose infrastructure for the genesis monorepo. Three stacks cover every stage of the development lifecycle.
+
+---
+
+## Stacks
+
+### `docker-compose.dev.yml` — Development
+
+Persistent local services with named volumes. Ports are offset into the `8000` range so they do not collide with app servers running on the typical `3000`/`4000` range. Intended to run continuously while developing; data survives container restarts.
+
+### `docker-compose.test.yml` — Integration Tests
+
+Ephemeral, no volumes. Ports are in the `7000` range, distinct from the dev stack so both can run simultaneously. Started automatically by CI and by the integration test suite's global setup; torn down after the run.
+
+### `docker-compose.testbed.yml` — Testbed Staging
+
+Fully isolated on a private Docker network (`testbed-net`). Services communicate by service name only — no host ports are exposed for the backing services. Includes a `testbed` app container (built from `apps/testbed`) and a Caddy reverse proxy on host ports `3200`/`3201`. Used for full E2E staging runs before graduation.
+
+---
+
+## Port Table
+
+| Service | Dev host port | Test host port | Testbed |
+|---------|--------------|----------------|---------|
+| SurrealDB (WS) | 8001 | 7004 | internal only |
+| Redis | 8002 | 7005 | internal only |
+| PostgreSQL | 8003 | 7006 | internal only |
+| Mailpit SMTP | 8004 | 7007 | internal only |
+| Mailpit Web UI | 8005 | 7008 | internal only |
+| Typesense | 8006 | 7009 | internal only |
+| Garage S3 API | 8900 | 7010 | internal only |
+| Garage S3 Admin | 8902 | 7011 | internal only |
+| Caddy HTTP | — | — | 3200 |
+| Caddy HTTPS | — | — | 3201 |
+
+---
+
+## Starting and Stopping
+
+### Development stack
+
+```bash
+# From repo root
+bun run --filter=@suaveplan/docker dev:up
+bun run --filter=@suaveplan/docker dev:down
+
+# Or directly from docker/
+docker compose -f docker-compose.dev.yml up -d
+docker compose -f docker-compose.dev.yml down
+```
+
+### Integration-test stack
+
+```bash
+bun run --filter=@suaveplan/docker test:up
+bun run --filter=@suaveplan/docker test:down
+
+# Or directly
+docker compose -f docker-compose.test.yml up -d
+docker compose -f docker-compose.test.yml down
+```
+
+### Testbed staging stack
+
+```bash
+bun run --filter=@suaveplan/docker testbed:up    # builds apps/testbed first
+bun run --filter=@suaveplan/docker testbed:down
+
+# Or directly
+docker compose -f docker-compose.testbed.yml up --build -d
+docker compose -f docker-compose.testbed.yml down
+```
+
+---
+
+## Health Verification
+
+After starting a stack, verify individual services are healthy:
+
+```bash
+# SurrealDB
+curl -sf http://localhost:8001/health && echo "surreal OK"
+
+# Redis
+redis-cli -p 8002 ping          # expect PONG
+
+# PostgreSQL
+pg_isready -h localhost -p 8003 -U postgres
+
+# Mailpit Web UI
+curl -sf http://localhost:8005/api/v1/messages && echo "mailpit OK"
+
+# Typesense
+curl -sf "http://localhost:8006/health" -H "X-TYPESENSE-API-KEY: test" && echo "typesense OK"
+
+# Garage S3
+curl -sf http://localhost:8900 && echo "garage OK"
+```
+
+For Docker-native health status:
+
+```bash
+docker compose -f docker-compose.dev.yml ps
+```
+
+---
+
+## Environment Variable Bridge
+
+The env-bridge pattern lets you point test fixtures at services you are already running locally — for example, a managed SurrealDB instance — instead of starting a Docker container. A fixture **only** enters passthrough mode when **all** of its required variables are set and non-empty. If any variable in a group is missing or empty, the fixture spins up its own container.
+
+### Setup
+
+```bash
+cp docker/.env.example docker/.env
+# Edit docker/.env — fill in only the groups you want to bypass
+```
+
+The `.env` file is gitignored. Never commit real credentials.
+
+### Variable Reference
+
+| Fixture | Required variables |
+|---------|--------------------|
+| SurrealDB | `SURREALDB_URL`, `SURREALDB_USERNAME`, `SURREALDB_PASSWORD` |
+| Redis | `REDIS_URL` |
+| PostgreSQL | `POSTGRES_URL` |
+| Mailpit | `MAILPIT_SMTP_URL`, `MAILPIT_API_URL` |
+| Typesense | `TYPESENSE_URL`, `TYPESENSE_API_KEY` |
+| Garage S3 | `GARAGE_S3_ENDPOINT`, `GARAGE_S3_ADMIN_ENDPOINT`, `GARAGE_S3_ACCESS_KEY_ID`, `GARAGE_S3_SECRET_ACCESS_KEY` |
+
+### Default values (dev stack)
+
+| Variable | Default |
+|----------|---------|
+| `SURREALDB_URL` | `ws://localhost:8001` |
+| `SURREALDB_USERNAME` | `root` |
+| `SURREALDB_PASSWORD` | `root` |
+| `REDIS_URL` | `redis://localhost:8002` |
+| `POSTGRES_URL` | `postgresql://postgres:postgres@localhost:8003/postgres` |
+| `MAILPIT_SMTP_URL` | `smtp://localhost:8004` |
+| `MAILPIT_API_URL` | `http://localhost:8005` |
+| `TYPESENSE_URL` | `http://localhost:8006` |
+| `TYPESENSE_API_KEY` | `test` |
+| `GARAGE_S3_ENDPOINT` | `http://localhost:8900` |
+| `GARAGE_S3_ADMIN_ENDPOINT` | `http://localhost:8902` |
+
+---
+
+## Garage S3 — Key Retrieval After First Run
+
+Garage generates a root key on first startup. The access key ID and secret are **not** set via environment variables — you must retrieve them after the first run:
+
+```bash
+# 1. Start the dev stack
+docker compose -f docker-compose.dev.yml up -d garage-s3
+
+# 2. Create a layout (single-node, zone z1, 1 GB capacity)
+docker compose -f docker-compose.dev.yml exec garage-s3 \
+  /garage layout assign -z z1 -c 1G $(
+    /garage node id 2>/dev/null | awk '{print $1}'
+  )
+docker compose -f docker-compose.dev.yml exec garage-s3 \
+  /garage layout apply --version 1
+
+# 3. Create a key
+docker compose -f docker-compose.dev.yml exec garage-s3 \
+  /garage key create my-key
+
+# 4. Copy the key ID and secret into docker/.env
+GARAGE_S3_ACCESS_KEY_ID=<key-id>
+GARAGE_S3_SECRET_ACCESS_KEY=<secret>
+```
+
+Refer to the [Garage documentation](https://garagehq.deuxfleurs.fr/documentation/quick-start/) for full setup instructions.
+
+---
+
+## Testbed Staging Environment
+
+The testbed stack builds `apps/testbed` locally and wires every service on the internal `testbed-net` network. Caddy proxies inbound traffic from `localhost:3200` to `testbed:3000`.
+
+```bash
+# Build and start
+docker compose -f docker-compose.testbed.yml up --build -d
+
+# Follow testbed app logs
+docker compose -f docker-compose.testbed.yml logs -f testbed
+
+# Run Playwright E2E against the staging URL
+PLAYWRIGHT_BASE_URL=http://localhost:3200 bunx turbo test:e2e --filter=@suaveplan/testbed
+
+# Tear down
+docker compose -f docker-compose.testbed.yml down
+```
+
+The testbed service reads all connection strings from its `environment` block (defined in `docker-compose.testbed.yml`) and does not rely on `.env`. Service-to-service communication uses Docker DNS names (`surrealdb`, `redis`, etc.).