# Docker Compose Dev

> Run a service stack locally using Docker Compose for prod-like development (e.g. PostgreSQL + app). Use when you need a real DB backend, multi-service integration, or want to reproduce production-like behavior locally.

- Skill: `matt-riley/docker-compose-dev` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add matt-riley/docker-compose-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matt-riley/docker-compose-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: GNU GPL v3
- Author: matt-riley (https://skillmd.com/u/matt-riley)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/matt-riley/docker-compose-dev

---


# Docker Compose dev stack

## Use this skill when

- A real DB backend or multi-service stack is needed for local or integration work.
- Reproducing production-like behaviour locally is the blocker.
- Debugging app/DB connectivity, startup order, or environment-variable wiring against the Compose stack.

## Do not use this skill when

- The task is purely configuration or env validation (use `configuration-env`).
- Unit tests can satisfy the change with in-memory or stub dependencies.

## Inputs to gather

- Whether an `.env.example` template exists and which credentials need real values.
- The app's health-check endpoint and port for post-start verification.
- Which services depend on which (for `depends_on` and healthcheck decisions).

## First move

- Copy `.env.example` to `.env`, bring the stack up, run migrations if not auto-applied, and verify the health endpoint.

## Outputs

- A compose-backed local stack started from the repo's `.env` template with required migrate or seed steps applied deliberately.
- Running service state confirmed via `docker compose ps`, logs, and/or the repo's health endpoint.
- An explicit teardown/reset outcome, including whether persistent volumes were preserved or intentionally destroyed.

## Quick start

```bash
cp .env.example .env              # copy env template; edit credentials as needed
make docker-compose-up            # or: docker compose up -d
```

Run any setup steps that do not run automatically (most setups require this):

```bash
make migrate-up                   # apply database migrations
```

Verify the app is healthy:

```bash
curl http://localhost:<PORT>/health
```

## Common operations

```bash
make docker-compose-logs          # or: docker compose logs -f
make docker-compose-ps            # or: docker compose ps
make docker-compose-down          # stop and remove containers
```

Full reset (wipes persistent volumes):

```bash
docker compose down -v            # removes containers AND volumes
```

Use `-v` only when you want to destroy all data (e.g. start fresh with a clean DB).

## Workflow

1. Copy `.env.example` to `.env` when missing; fill required secrets without committing `.env`.
2. Bring the stack up with the repo's compose command.
3. Run migrations/seeds explicitly if compose does not apply them automatically.
4. Verify with `docker compose ps`, service logs, and the health endpoint.
5. Exercise the local path the user cares about (API, worker, UI) against real compose services.
6. On failure, isolate the unhealthy service, fix config/volumes/ports, and re-verify.
7. Tear down deliberately: preserve volumes by default; only use `-v` when a full data wipe is intended.

## Guardrails

- Migrations are **not** run automatically by `docker compose up` — run them explicitly after services start.
- If credentials in `.env` change, update any `DATABASE_URL` or connection strings that reference them.
- Use Compose for integration/E2E testing against real services; use in-memory or stub variants for unit tests.
- Never use `docker compose down -v` unless you intentionally want to destroy all persistent data.

## Troubleshooting

| Symptom                 | Fix                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------- |
| App crashes immediately | Check logs: `docker compose logs app`                                                   |
| DB connection refused   | Confirm DB service is healthy before the app starts; add `depends_on` with health check |
| Migrations fail         | Verify `DATABASE_URL` matches the credentials in `.env` and the DB is reachable         |

## Validation

- Confirm `docker compose ps` or the repo wrapper shows the expected services running.
- Run the service health check or smoke test against the compose-backed app.
- Confirm migrations and required seed/setup steps were applied deliberately, not assumed.
- Before teardown, decide whether volumes should be preserved or intentionally destroyed.

## Reference files

- Read `references/examples.md` when you need concrete user utterances, expected behaviour, or a model answer shape to mirror.
- Read `references/edge-cases.md` when the request is a near miss, partially matches this skill, or the first attempt fails.

