@brunosps00/dev-workflow 0.7.0 → 0.8.0

package/scaffold/skills/docker-compose-recipes/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: docker-compose-recipes
+description: Validated docker-compose service blocks (postgres, redis, mailhog, minio, meilisearch, jaeger, traefik, etc.) for dev and prod, composed by /dw-new-project and /dw-dockerize. Each service is a standalone YAML with healthcheck, named volume, and env conventions.
+allowed-tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+---
+
+# docker-compose-recipes
+
+This skill is a curated library of **validated `docker-compose` service blocks** that other dev-workflow commands (`/dw-new-project`, `/dw-dockerize`) merge into a final `docker-compose.dev.yml` or `docker-compose.prod.yml`.
+
+## Why a skill (not a template)
+
+- Each service file is independently maintainable. Bumping Postgres from 16 to 17 is a one-file change.
+- Discoverable by AI agents in any project the user installs dev-workflow into — they can read the recipes when reasoning about local infra.
+- Reusable by future commands (e.g., `dw-add-service`, `dw-bench-services`) without duplication.
+
+## When to Use
+
+Read this skill when:
+
+- Composing `docker-compose.*.yml` for a new project (`/dw-new-project`).
+- Adding services to an existing project (`/dw-dockerize`, `--audit` mode).
+- Answering user questions about which Docker image / version / healthcheck to use for a given service.
+- Producing `.env.example` entries that match the env vars expected by these services.
+
+Do NOT use when:
+
+- The user asks for a service NOT in `services/` — propose the user add a new recipe to this skill instead of inventing a one-off block.
+- The project does not need containerized infra (e.g., serverless-only, already-managed cloud DB).
+
+## How to Compose
+
+1. **Pick the services** the user selected during the interview (or detected by `/dw-dockerize`).
+2. **Read each `services/<name>.yml`** as a standalone block. Each file declares ONE top-level service.
+3. **Merge into the final compose file** by appending each block under a single `services:` map. Reuse the same volume name across services that share storage (rare).
+4. **Resolve port conflicts**: the recipes use widely-used defaults; if multiple services collide (e.g., two HTTP UIs on 8080), shift the second one in the merged compose and add a note in the README port table.
+5. **Wire env vars**: every recipe references `.env`-style variables. Consolidate them into the project's single `.env.example` using the conventions in `references/env-conventions.md`.
+6. **Healthchecks**: each recipe includes a healthcheck. Other services that depend on it should declare `depends_on: { <name>: { condition: service_healthy } }`. See `references/healthcheck-patterns.md`.
+7. **Dev vs Prod**: recipes default to dev (bind mounts, exposed ports, no restart policy). For prod, apply the transforms in `references/prod-vs-dev.md` (named volumes, internal ports, `restart: unless-stopped`, secrets via env, no UI exposure unless behind a proxy).
+
+## Available Services
+
+Each row points to `services/<name>.yml`.
+
+| Service | Use | Default port(s) | Recipe |
+|---------|-----|-----------------|--------|
+| Postgres 16 (alpine) | Relational DB | `5432` | `services/postgres.yml` |
+| MySQL 8 | Relational DB | `3306` | `services/mysql.yml` |
+| Redis 7 (alpine) | Cache, pub/sub, BullMQ backend | `6379` | `services/redis.yml` |
+| Memcached 1.6 (alpine) | Cache | `11211` | `services/memcached.yml` |
+| RabbitMQ 3 (management-alpine) | Message broker + UI | `5672`, UI `15672` | `services/rabbitmq.yml` |
+| LocalStack | AWS-compatible local (S3, SQS, SNS, DynamoDB) | `4566` | `services/localstack.yml` |
+| MailHog | Default email-in-dev (capture only, never sends) | SMTP `1025`, UI `8025` | `services/mailhog.yml` |
+| Mailpit | Modern MailHog alternative | SMTP `1025`, UI `8025` | `services/mailpit.yml` |
+| smtp4dev | Windows-friendly SMTP capture | SMTP `2525`, UI `5000` | `services/smtp4dev.yml` |
+| MinIO | S3-compatible local | API `9000`, UI `9001` | `services/minio.yml` |
+| Meilisearch | Search engine (lightweight) | `7700` | `services/meilisearch.yml` |
+| Typesense | Search engine alternative | `8108` | `services/typesense.yml` |
+| Elasticsearch 8 | Search engine (heavyweight) | `9200` | `services/elasticsearch.yml` |
+| Jaeger all-in-one | OTel collector + UI | OTLP `4317`/`4318`, UI `16686` | `services/jaeger.yml` |
+| Traefik 3 | Reverse proxy + dev TLS | HTTP `80`, HTTPS `443`, dashboard `8080` | `services/traefik.yml` |
+
+## References
+
+- `references/compose-composition.md` — how to merge recipes into a single `docker-compose.dev.yml`.
+- `references/env-conventions.md` — how env var names are normalized (e.g., `POSTGRES_USER` → also exposed as `DATABASE_URL` for app code).
+- `references/healthcheck-patterns.md` — what each service's healthcheck looks like and how to chain `depends_on`.
+- `references/prod-vs-dev.md` — what changes when a recipe goes to `docker-compose.prod.yml`.
+
+## Rules
+
+- **Pin major.minor** in every `image:` line. Patch updates are safe; major bumps are deliberate.
+- **Always include healthcheck**. No service is allowed to be opaque about readiness.
+- **Default to dev**. Prod transforms are explicit (see `prod-vs-dev.md`).
+- **Email-in-dev defaults to MailHog**. The user must opt OUT of capture-only email for dev — never silently route to a real SMTP.
+- **Secrets never in the recipe**. Env vars reference `.env`; defaults in the recipe are OK only for non-secret config.
+
+## Inspired by
+
+Hand-curated by dev-workflow. Service defaults follow upstream documentation (Docker Hub `postgres`, `redis`, `mailhog/mailhog`, `minio/minio`, `getmeili/meilisearch`, `jaegertracing/all-in-one`, `traefik`). Healthcheck patterns adapted from `docker-library/healthcheck` and the official compose docs.

package/scaffold/skills/docker-compose-recipes/references/compose-composition.md

@@ -0,0 +1,91 @@
+# Composing a final `docker-compose.dev.yml`
+
+This file describes how `/dw-new-project` and `/dw-dockerize` merge the standalone service blocks under `services/` into a single working compose file.
+
+## The merge algorithm
+
+1. **Pick the selected services.** From the interview answers (or from stack detection in `dw-dockerize`), get the list of services to include. Example: `[postgres, redis, mailhog, minio]`.
+2. **Read each `services/<name>.yml`** as a standalone fragment. Each file declares ONE top-level service block (e.g., `postgres:`) plus comments at the bottom describing the volumes block to merge.
+3. **Concatenate under a single `services:` map.** Indent each block under `services:` in the final file. Order does not matter for compose, but for readability sort by tier: storage → cache/queue → search → email → observability → proxy.
+4. **Collect the volumes.** Each recipe's comments list the named volumes it needs. Aggregate them under a top-level `volumes:` block. Example:
+
+   ```yaml
+   volumes:
+     postgres_data: {}
+     redis_data: {}
+     minio_data: {}
+   ```
+
+5. **Add a network (optional but recommended).** Default Docker compose creates one project network already, so explicit declaration is only needed if you want a custom name or external network.
+
+6. **Resolve port collisions.** The recipes use upstream defaults. If two selected services share a port (rare; mostly UIs on `8080`), shift the second one and document in the README port table.
+
+7. **Wire `depends_on` with health gates** for app services that depend on infra:
+
+   ```yaml
+   api:
+     depends_on:
+       postgres:
+         condition: service_healthy
+       redis:
+         condition: service_healthy
+   ```
+
+8. **Add the app service(s) at the end.** For monorepo projects, declare an `api` service (and `web` if backend serves the frontend) that builds from the local Dockerfile.dev and binds the source as a volume for hot reload.
+
+## Final file shape
+
+```yaml
+# Generated by /dw-new-project on YYYY-MM-DD
+# Edit freely. Recipes live in .agents/skills/docker-compose-recipes/
+
+services:
+  # --- storage tier ---
+  postgres:
+    # ... contents from services/postgres.yml
+
+  # --- cache tier ---
+  redis:
+    # ... contents from services/redis.yml
+
+  # --- email-in-dev (capture only) ---
+  mailhog:
+    # ... contents from services/mailhog.yml
+
+  # --- object storage ---
+  minio:
+    # ... contents from services/minio.yml
+
+  # --- application ---
+  api:
+    build:
+      context: ./apps/api
+      dockerfile: Dockerfile.dev
+    env_file: .env
+    volumes:
+      - ./apps/api:/app
+      - /app/node_modules     # avoid host node_modules clobbering container's
+    ports:
+      - "${API_PORT:-3001}:3001"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      mailhog:
+        condition: service_started
+      minio:
+        condition: service_healthy
+
+volumes:
+  postgres_data: {}
+  redis_data: {}
+  minio_data: {}
+```
+
+## Common mistakes to avoid
+
+- **Don't leave secrets as defaults in the compose file.** All recipes default to dev passwords; override via `.env` even in dev so a typo doesn't ship a default to a server.
+- **Don't omit healthchecks.** They drive `depends_on` correctness. An app starting before Postgres is ready is a class of flaky dev-day bugs.
+- **Don't share volumes across services with different ownership** (e.g., postgres + minio). Each gets its own named volume.
+- **Don't expose the management UI ports of brokers/search engines on `0.0.0.0` in dev environments shared with others.** Bind to `127.0.0.1:<port>:<port>` if multi-tenant.

package/scaffold/skills/docker-compose-recipes/references/env-conventions.md

@@ -0,0 +1,51 @@
+# Env var conventions
+
+All recipes reference env vars via `${VAR:-default}` so a project's `.env` (or `.env.example`) is the single source of truth.
+
+## Naming pattern
+
+- **Service-scoped** vars use the upstream image's convention: `POSTGRES_USER`, `MYSQL_ROOT_PASSWORD`, `MEILI_MASTER_KEY`, etc. This avoids surprises when reading the image's documentation.
+- **Application-scoped** vars use a generic name that spans implementations: `DATABASE_URL`, `REDIS_URL`, `SMTP_HOST`, `AWS_ENDPOINT_URL`. The application reads these, not the service-specific ones.
+- **Port overrides** use `<SERVICE>_PORT` (or `<SERVICE>_<ROLE>_PORT` when there are several): `POSTGRES_PORT`, `MAILHOG_SMTP_PORT`, `MAILHOG_UI_PORT`, `RABBITMQ_PORT`, `RABBITMQ_UI_PORT`.
+
+## Mapping between service vars and app vars
+
+When a project uses Postgres, the `.env.example` should declare BOTH the service-side vars (so the recipe works) AND the application-side derived URL (so app code reads one variable):
+
+```dotenv
+# Postgres (consumed by the postgres service)
+POSTGRES_USER=app
+POSTGRES_PASSWORD=app
+POSTGRES_DB=app
+POSTGRES_PORT=5432
+
+# Application-side connection string
+DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+```
+
+Compose performs variable substitution in `.env` references, so the application sees `DATABASE_URL` already-resolved.
+
+## What goes in `.env.example` vs `.env`
+
+- `.env.example` — committed. Holds DEFAULTS that are safe for dev and template values for prod.
+- `.env` — gitignored. Real values for the user's local machine.
+
+Never commit a `.env`. Always commit a `.env.example`.
+
+## Common cross-service derivations
+
+| Use case | Derived variable | Source |
+|----------|------------------|--------|
+| Postgres URL | `DATABASE_URL` | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` |
+| MySQL URL | `DATABASE_URL` | `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` |
+| Redis URL | `REDIS_URL` | `REDIS_PASSWORD` (if set) |
+| RabbitMQ URL | `AMQP_URL` | `RABBITMQ_USER`, `RABBITMQ_PASSWORD` |
+| AWS-compatible | `AWS_ENDPOINT_URL`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | LocalStack: `test`/`test`. MinIO: `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD` |
+| SMTP | `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_SECURE` | Service hostname (`mailhog`/`mailpit`/`smtp4dev`) + recipe's SMTP port |
+| OTel | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://jaeger:4318` |
+
+## Reserved names
+
+The recipes use these env var names. Do NOT reuse them for unrelated config:
+
+`POSTGRES_*`, `MYSQL_*`, `MEILI_*`, `MINIO_*`, `RABBITMQ_*`, `MAILHOG_*`, `MAILPIT_*`, `SMTP4DEV_*`, `JAEGER_*`, `TRAEFIK_*`, `LOCALSTACK_*`, `ELASTIC_*`, `TYPESENSE_*`, `MEMCACHED_*`, `REDIS_*`.

package/scaffold/skills/docker-compose-recipes/references/healthcheck-patterns.md

@@ -0,0 +1,54 @@
+# Healthcheck patterns
+
+Every recipe ships a healthcheck. App services that depend on infra MUST gate startup on these via `depends_on: { <service>: { condition: service_healthy } }`.
+
+## Per-service shapes
+
+| Service | Test command | Why |
+|---------|--------------|-----|
+| Postgres | `pg_isready -U $USER -d $DB` | Distinguishes "process up" from "ready to accept queries" |
+| MySQL | `mysqladmin ping` | Same — process up != accepting connections |
+| Redis | `redis-cli ping` | Returns `PONG` only when the server is fully initialized |
+| Memcached | `echo stats | nc -w 1 localhost 11211 \| grep -q uptime` | Memcached has no native ping; stats command is the cheapest readiness signal |
+| RabbitMQ | `rabbitmq-diagnostics ping` | Built-in; takes ~30s to be ready, hence `start_period: 30s` |
+| LocalStack | `curl -sf http://localhost:4566/_localstack/health \| grep -q running` | Internal endpoint reports per-service readiness |
+| MailHog | `wget --spider http://localhost:8025` | UI port responds when SMTP is also ready |
+| Mailpit | `wget --spider http://localhost:8025` | Same |
+| smtp4dev | `wget --spider http://localhost:80` | UI on internal port 80 |
+| MinIO | `curl -f http://localhost:9000/minio/health/live` | Documented liveness endpoint |
+| Meilisearch | `curl -f http://localhost:7700/health` | Documented |
+| Typesense | `curl -f http://localhost:8108/health` | Documented |
+| Elasticsearch | Auth + `_cluster/health \| grep -E 'green|yellow'` | Yellow is OK in single-node dev (no replicas) |
+| Jaeger | `wget --spider http://localhost:14269/` | Admin/health port (separate from UI) |
+| Traefik | `wget --spider http://localhost:8080/ping` | Built-in ping endpoint |
+
+## Tuning
+
+Default values across recipes:
+- `interval: 5-10s` (how often the check runs)
+- `timeout: 3-5s` (how long the check is allowed to take)
+- `retries: 5-10` (how many failures before unhealthy)
+- `start_period: 5-60s` (grace window during initial boot — Elasticsearch and RabbitMQ get the most because they take longest to come up)
+
+Adjust upward only if your machine is slow or your image is custom-built and slow to start. Adjust downward only if you fully understand the startup curve.
+
+## Chaining `depends_on`
+
+```yaml
+api:
+  depends_on:
+    postgres:
+      condition: service_healthy   # waits for the healthcheck to pass
+    redis:
+      condition: service_healthy
+    mailhog:
+      condition: service_started   # MailHog is light enough that started == ready
+```
+
+`service_healthy` is the strictest gate — no traffic until the healthcheck has passed at least once. Use it for all data stores. Use `service_started` only for stateless services (proxy, mail capture).
+
+## Common mistakes
+
+- **Forgetting `start_period`** — without it, the first few healthcheck failures during boot count toward `retries` and the service is marked unhealthy before it ever had a chance.
+- **Using `tcp://host:port` checks** — they only test that the port is open, not that the application behind it is ready (e.g., Postgres accepts TCP before it accepts queries).
+- **Setting `retries: 0`** — this is "fail on first miss." Always allow at least 3 retries to absorb transient hiccups.

package/scaffold/skills/docker-compose-recipes/references/prod-vs-dev.md

@@ -0,0 +1,85 @@
+# Dev vs Prod — what changes in each recipe
+
+The recipes default to **dev**. When `/dw-dockerize --prod` (or `--both`) emits a production compose, apply these transforms.
+
+## Universal changes
+
+| Aspect | Dev | Prod |
+|--------|-----|------|
+| Image tag | `<image>:<major>-alpine` (e.g., `postgres:16-alpine`) | Pin to a patch (`postgres:16.4-alpine`); no `:latest` ever |
+| Restart policy | `unless-stopped` is fine | `always` for stateless, `unless-stopped` for stateful |
+| Public ports | Mapped (`5432:5432`) for host access | NOT mapped — services talk over the internal network only; access via bastion/VPN |
+| Bind mounts | Source code mounted for hot reload | NEVER. Code is baked into the image. |
+| Named volumes | OK with default driver | Use external volume drivers when running on swarm/k8s; back up regularly |
+| Env / secrets | `.env` is fine | Secrets via Docker secrets, AWS Parameter Store, Vault, or platform-native — NOT `.env` files committed anywhere |
+| Healthcheck | Same | Same — keep them, they drive orchestrator failover |
+| Logging | Default driver | `json-file` with rotation, or ship to a log aggregator (Loki, CloudWatch) |
+| Resource limits | None (machine has plenty) | `mem_limit`, `cpus` set per service to prevent runaway containers |
+
+## Per-service prod transforms
+
+### Postgres / MySQL / Redis (data tier)
+
+- Drop public port.
+- Move all credentials to secrets (compose's `secrets:` block, or Docker swarm secrets, or external vault).
+- Increase `start_period` to 60-120s (large data dirs take longer to recover).
+- Set up a logical backup (`pg_dump`/`mysqldump`) on a schedule, persisted off-host.
+- For Redis: enable AOF persistence (`appendonly yes`) and set `requirepass`.
+
+### RabbitMQ
+
+- Use `rabbitmq:3-alpine` (no management UI baked in) and run management as a separate service if needed.
+- Drop port `15672`. Drop default user; create real users via `rabbitmqctl add_user` on first boot.
+- Mount a custom `rabbitmq.conf` for clustering, queue limits, and TLS.
+
+### MinIO / S3
+
+- In prod, prefer real S3 (or another managed object store). MinIO in prod requires HA (4+ nodes), erasure coding tuning, and ongoing operational care.
+- If you keep MinIO, generate strong credentials and rotate them; never use defaults.
+
+### LocalStack
+
+- **Remove entirely from prod compose.** LocalStack is dev-only.
+- Replace with the real AWS endpoints; `AWS_ENDPOINT_URL` becomes unset (default to AWS).
+
+### MailHog / Mailpit / smtp4dev
+
+- **Remove entirely from prod compose.** Email-in-dev tools are dev-only.
+- Replace with a real provider via `SMTP_*` or API client (SendGrid, Resend, Postmark, SES).
+
+### Jaeger all-in-one
+
+- **Replace with split deployment** in prod: `jaeger-collector`, `jaeger-query`, plus Cassandra or Elasticsearch as storage. Or use a managed APM.
+
+### Traefik
+
+- Remove `--api.insecure=true`.
+- Use a file or KV provider; don't expose the Docker socket if you can avoid it.
+- Configure ACME (Let's Encrypt) for real TLS.
+- Bind dashboard to a private network, behind basic auth.
+
+### Meilisearch / Typesense
+
+- Set the prod env (`MEILI_ENV=production`) and a strong API/master key.
+- Consider clustering for HA (Typesense supports 3-node clusters; Meilisearch v1.x is single-instance — use replication carefully).
+
+### Elasticsearch
+
+- Single-node is dev-only. Run a 3-node cluster minimum.
+- Enable TLS on transport AND HTTP layers (`xpack.security.transport.ssl.enabled=true`, `xpack.security.http.ssl.enabled=true`).
+- Tune heap (`ES_JAVA_OPTS`) per host; don't exceed 50% of host RAM and don't exceed 31GB.
+
+## File-level conventions
+
+- **Dev compose:** `docker-compose.dev.yml` (or `docker-compose.yml` if there's only one).
+- **Prod compose:** `docker-compose.prod.yml`. Run with `docker compose -f docker-compose.prod.yml up`.
+- **Common base:** if both files share a lot, factor common service definitions into `docker-compose.yml` and use `-f` overrides per environment.
+
+## What `/dw-dockerize --prod` should NEVER do
+
+- Ship secrets in committed files.
+- Use `:latest` tags.
+- Expose data-tier ports publicly.
+- Include MailHog / Mailpit / smtp4dev / LocalStack.
+- Skip healthchecks.
+- Forget to set non-root `USER` in the application Dockerfile.

package/scaffold/skills/docker-compose-recipes/services/elasticsearch.yml

@@ -0,0 +1,34 @@
+# Elasticsearch 8 — full search + analytics. Heavyweight: only choose if you need ES specifically.
+# Env vars: ELASTIC_PASSWORD, ELASTICSEARCH_PORT (default 9200)
+# Application-side: ELASTICSEARCH_URL=http://elastic:${ELASTIC_PASSWORD}@elasticsearch:9200
+
+elasticsearch:
+  image: docker.elastic.co/elasticsearch/elasticsearch:8.15.0
+  restart: unless-stopped
+  environment:
+    discovery.type: single-node
+    xpack.security.enabled: "true"
+    ELASTIC_PASSWORD: ${ELASTIC_PASSWORD:-elastic}
+    ES_JAVA_OPTS: "-Xms512m -Xmx512m"
+  ports:
+    - "${ELASTICSEARCH_PORT:-9200}:9200"
+  volumes:
+    - elasticsearch_data:/usr/share/elasticsearch/data
+  healthcheck:
+    test: ["CMD-SHELL", "curl -fsu elastic:${ELASTIC_PASSWORD:-elastic} http://localhost:9200/_cluster/health | grep -E 'green|yellow'"]
+    interval: 10s
+    timeout: 5s
+    retries: 10
+    start_period: 60s
+  ulimits:
+    memlock:
+      soft: -1
+      hard: -1
+
+# volumes:
+#   elasticsearch_data: {}
+#
+# Prod notes:
+# - Single-node is for dev only. Run a 3-node cluster minimum in prod with proper data tiers.
+# - Tune ES_JAVA_OPTS per host; default 512m is enough for dev but too small for any real index.
+# - Enable TLS (xpack.security.transport.ssl.enabled=true) and rotate ELASTIC_PASSWORD.

package/scaffold/skills/docker-compose-recipes/services/jaeger.yml

@@ -0,0 +1,24 @@
+# Jaeger all-in-one — OTel collector + storage + UI. Easiest tracing setup for dev.
+# Env vars: JAEGER_UI_PORT (default 16686), JAEGER_OTLP_GRPC_PORT (default 4317), JAEGER_OTLP_HTTP_PORT (default 4318)
+# Application-side: OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318 (HTTP) or http://jaeger:4317 (gRPC)
+
+jaeger:
+  image: jaegertracing/all-in-one:1.60
+  restart: unless-stopped
+  environment:
+    COLLECTOR_OTLP_ENABLED: "true"
+  ports:
+    - "${JAEGER_UI_PORT:-16686}:16686"
+    - "${JAEGER_OTLP_GRPC_PORT:-4317}:4317"
+    - "${JAEGER_OTLP_HTTP_PORT:-4318}:4318"
+  healthcheck:
+    test: ["CMD-SHELL", "wget --quiet --spider http://localhost:14269/ || exit 1"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# Prod notes:
+# - all-in-one stores traces in memory. NEVER use for prod.
+# - In prod, run jaeger-collector + jaeger-query separately, with Cassandra/Elasticsearch as storage.
+# - Or replace Jaeger with a managed APM (Honeycomb, Datadog, Grafana Tempo, Sentry tracing).

package/scaffold/skills/docker-compose-recipes/services/localstack.yml

@@ -0,0 +1,30 @@
+# LocalStack — AWS-compatible local (S3, SQS, SNS, DynamoDB, etc.)
+# Env vars: LOCALSTACK_PORT (default 4566), LOCALSTACK_SERVICES (comma list, e.g., "s3,sqs,sns,dynamodb")
+# Application-side: AWS_ENDPOINT_URL=http://localstack:4566; AWS_ACCESS_KEY_ID=test; AWS_SECRET_ACCESS_KEY=test; AWS_REGION=us-east-1
+
+localstack:
+  image: localstack/localstack:3
+  restart: unless-stopped
+  environment:
+    SERVICES: ${LOCALSTACK_SERVICES:-s3,sqs,sns,dynamodb}
+    DEBUG: ${LOCALSTACK_DEBUG:-0}
+    LS_LOG: ${LOCALSTACK_LOG:-warn}
+    AWS_DEFAULT_REGION: us-east-1
+  ports:
+    - "${LOCALSTACK_PORT:-4566}:4566"
+  volumes:
+    - localstack_data:/var/lib/localstack
+    - /var/run/docker.sock:/var/run/docker.sock
+  healthcheck:
+    test: ["CMD-SHELL", "curl -sf http://localhost:4566/_localstack/health | grep -q '\"running\"'"]
+    interval: 10s
+    timeout: 5s
+    retries: 10
+    start_period: 20s
+
+# volumes:
+#   localstack_data: {}
+#
+# Prod notes:
+# - LocalStack is for DEV ONLY. In prod, point AWS_ENDPOINT_URL back to real AWS and remove this service.
+# - The Docker socket mount is required for Lambda emulation; remove if Lambda is not used.

package/scaffold/skills/docker-compose-recipes/services/mailhog.yml

@@ -0,0 +1,23 @@
+# MailHog — DEV-ONLY email capture (NEVER sends real mail)
+# This is the dev-workflow DEFAULT for email-in-dev so the project cannot accidentally email real users.
+# Env vars: MAILHOG_SMTP_PORT (default 1025), MAILHOG_UI_PORT (default 8025)
+# Application-side SMTP config:
+#   SMTP_HOST=mailhog ; SMTP_PORT=1025 ; SMTP_USER= ; SMTP_PASSWORD= ; SMTP_SECURE=false
+
+mailhog:
+  image: mailhog/mailhog:latest
+  restart: unless-stopped
+  ports:
+    - "${MAILHOG_SMTP_PORT:-1025}:1025"
+    - "${MAILHOG_UI_PORT:-8025}:8025"
+  healthcheck:
+    test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:8025"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# Prod notes:
+# - MailHog must NEVER ship to prod. Replace with a real SMTP relay or transactional email API
+#   (SendGrid, Resend, Postmark, SES) when promoting docker-compose.dev.yml to prod.
+# - Open the UI at http://localhost:8025 to inspect captured mail; nothing leaves the host.

package/scaffold/skills/docker-compose-recipes/services/mailpit.yml

@@ -0,0 +1,27 @@
+# Mailpit — modern alternative to MailHog (active maintenance, full-text search, REST API)
+# Env vars: MAILPIT_SMTP_PORT (default 1025), MAILPIT_UI_PORT (default 8025)
+# Application-side SMTP config: same as MailHog (drop-in replacement)
+
+mailpit:
+  image: axllent/mailpit:latest
+  restart: unless-stopped
+  ports:
+    - "${MAILPIT_SMTP_PORT:-1025}:1025"
+    - "${MAILPIT_UI_PORT:-8025}:8025"
+  environment:
+    MP_MAX_MESSAGES: ${MAILPIT_MAX_MESSAGES:-500}
+    MP_DATABASE: /data/mailpit.db
+  volumes:
+    - mailpit_data:/data
+  healthcheck:
+    test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:8025"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# volumes:
+#   mailpit_data: {}
+#
+# Prod notes:
+# - DEV ONLY. Do not ship to prod. See mailhog.yml notes for prod email guidance.

package/scaffold/skills/docker-compose-recipes/services/meilisearch.yml

@@ -0,0 +1,28 @@
+# Meilisearch — lightweight, opinionated search engine
+# Env vars: MEILI_MASTER_KEY, MEILISEARCH_PORT (default 7700)
+# Application-side: MEILI_HTTP_ADDR=http://meilisearch:7700; MEILI_MASTER_KEY=${MEILI_MASTER_KEY}
+
+meilisearch:
+  image: getmeili/meilisearch:v1.10
+  restart: unless-stopped
+  environment:
+    MEILI_MASTER_KEY: ${MEILI_MASTER_KEY:-meili-dev-key-change-me}
+    MEILI_ENV: ${MEILI_ENV:-development}
+    MEILI_NO_ANALYTICS: "true"
+  ports:
+    - "${MEILISEARCH_PORT:-7700}:7700"
+  volumes:
+    - meilisearch_data:/meili_data
+  healthcheck:
+    test: ["CMD", "curl", "-f", "http://localhost:7700/health"]
+    interval: 10s
+    timeout: 3s
+    retries: 5
+    start_period: 5s
+
+# volumes:
+#   meilisearch_data: {}
+#
+# Prod notes:
+# - Set MEILI_ENV=production and provide a strong MEILI_MASTER_KEY (≥16 chars).
+# - Never expose Meilisearch directly to the internet without auth + a reverse proxy.

package/scaffold/skills/docker-compose-recipes/services/memcached.yml

@@ -0,0 +1,19 @@
+# Memcached 1.6 — cache (no persistence)
+# Env vars: MEMCACHED_PORT (default 11211), MEMCACHED_MEMORY_MB (default 64)
+
+memcached:
+  image: memcached:1.6-alpine
+  restart: unless-stopped
+  command: -m ${MEMCACHED_MEMORY_MB:-64}
+  ports:
+    - "${MEMCACHED_PORT:-11211}:11211"
+  healthcheck:
+    test: ["CMD-SHELL", "echo stats | nc -w 1 localhost 11211 | grep -q uptime"]
+    interval: 5s
+    timeout: 3s
+    retries: 10
+    start_period: 3s
+
+# Prod notes:
+# - Memcached has no auth. NEVER expose its port publicly. Internal network only.
+# - For multi-host setups, use a managed cache (Redis, ElastiCache).

package/scaffold/skills/docker-compose-recipes/services/minio.yml

@@ -0,0 +1,30 @@
+# MinIO — S3-compatible object storage (dev replacement for AWS S3)
+# Env vars: MINIO_ROOT_USER, MINIO_ROOT_PASSWORD, MINIO_API_PORT (default 9000), MINIO_UI_PORT (default 9001)
+# Application-side: AWS_ENDPOINT_URL=http://minio:9000; AWS_ACCESS_KEY_ID=${MINIO_ROOT_USER}; AWS_SECRET_ACCESS_KEY=${MINIO_ROOT_PASSWORD}
+
+minio:
+  image: minio/minio:latest
+  restart: unless-stopped
+  command: server /data --console-address ":9001"
+  environment:
+    MINIO_ROOT_USER: ${MINIO_ROOT_USER:-minio}
+    MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-minio12345}
+  ports:
+    - "${MINIO_API_PORT:-9000}:9000"
+    - "${MINIO_UI_PORT:-9001}:9001"
+  volumes:
+    - minio_data:/data
+  healthcheck:
+    test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+    interval: 10s
+    timeout: 5s
+    retries: 5
+    start_period: 5s
+
+# volumes:
+#   minio_data: {}
+#
+# Prod notes:
+# - In prod, replace with real S3 (or another managed object store). MinIO is great in dev,
+#   acceptable in prod only if you understand the operational requirements (HA, erasure coding, replication).
+# - Always rotate MINIO_ROOT_PASSWORD; default credentials must NOT survive past local dev.

package/scaffold/skills/docker-compose-recipes/services/mysql.yml

@@ -0,0 +1,30 @@
+# MySQL 8 — relational DB
+# Env vars referenced: MYSQL_ROOT_PASSWORD, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE, MYSQL_PORT (default 3306)
+# Application-side: DATABASE_URL=mysql://${MYSQL_USER}:${MYSQL_PASSWORD}@mysql:3306/${MYSQL_DATABASE}
+
+mysql:
+  image: mysql:8.4
+  restart: unless-stopped
+  command: --default-authentication-plugin=mysql_native_password
+  environment:
+    MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root}
+    MYSQL_USER: ${MYSQL_USER:-app}
+    MYSQL_PASSWORD: ${MYSQL_PASSWORD:-app}
+    MYSQL_DATABASE: ${MYSQL_DATABASE:-app}
+  ports:
+    - "${MYSQL_PORT:-3306}:3306"
+  volumes:
+    - mysql_data:/var/lib/mysql
+  healthcheck:
+    test: ["CMD-SHELL", "mysqladmin ping -h localhost -u${MYSQL_USER:-app} -p${MYSQL_PASSWORD:-app}"]
+    interval: 5s
+    timeout: 3s
+    retries: 10
+    start_period: 15s
+
+# volumes:
+#   mysql_data: {}
+#
+# Prod notes:
+# - Use secrets for MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD; drop public port.
+# - Consider Percona or MariaDB as drop-in alternatives if licensing is a concern.

package/scaffold/skills/docker-compose-recipes/services/postgres.yml

@@ -0,0 +1,30 @@
+# Postgres 16 — relational DB
+# Env vars referenced: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_PORT (default 5432)
+# Application-side: derive DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+
+postgres:
+  image: postgres:16-alpine
+  restart: unless-stopped
+  environment:
+    POSTGRES_USER: ${POSTGRES_USER:-app}
+    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-app}
+    POSTGRES_DB: ${POSTGRES_DB:-app}
+  ports:
+    - "${POSTGRES_PORT:-5432}:5432"
+  volumes:
+    - postgres_data:/var/lib/postgresql/data
+  healthcheck:
+    test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-app} -d ${POSTGRES_DB:-app}"]
+    interval: 5s
+    timeout: 3s
+    retries: 10
+    start_period: 5s
+
+# volumes block to merge:
+# volumes:
+#   postgres_data: {}
+#
+# Prod notes:
+# - Move POSTGRES_PASSWORD to a secret (file_env or external secrets manager).
+# - Drop the public port mapping; expose only via internal network or a bastion.
+# - Pin to a specific patch version in production manifests (e.g., postgres:16.4-alpine).