Write a Docker Compose dev environment

A local environment earns its keep when a new developer can clone the repo, run one command and have a working app with realistic data in minutes, and when "works on my machine" bugs stop coming from version drift. Compose files usually fall short in the same ways: latest images that differ from production, apps that start before the database accepts connections, data lost on every restart, secrets committed in the file, ports exposed on every network interface, and no seed data, so everyone builds their own by hand.

Write a Docker Compose development environment for: [SERVICES] Only if [STACK] is given:

Stack: [STACK] Only if [PRODUCTION_NOTES] is given:

Production: [PRODUCTION_NOTES]

1. If the repository is available, read the existing Dockerfiles, dependency manifests, environment variable usage and any current compose file first, and build on them.
2. Pin every dependency image to the same major and minor version as production (for example postgres:16.4), never latest. Where production uses a managed service with no local equivalent, choose a compatible local stand-in and record the gap.
3. Write compose.yaml following the current Compose Specification (no top-level version: key):

• App services built from the repo's Dockerfile, using a development target or stage if one exists, with the source bind-mounted for hot reload (or a develop.watch section), and dependency folders kept inside the container so host and container builds do not clash.
• A healthcheck on every dependency using its own readiness command (pg_isready, redis-cli ping, an HTTP health endpoint), and depends_on with condition: service_healthy on the app services.
• Named volumes for all persistent data; no anonymous volumes for data that should survive a restart.
• Ports published on 127.0.0.1 only, with defaults that avoid common clashes and can be overridden from the env file.
• Optional services (admin UIs, observability, workers that are not always needed) behind profiles.

1. Put configuration in an env file: write .env.example with every variable, safe local defaults and a comment per variable; the real .env stays git-ignored. Never put production credentials or real secrets anywhere.
2. Provide seed data: database init scripts or a one-shot seed service that runs after the database is healthy (condition: service_completed_successfully for services that depend on it), is idempotent, and creates a few realistic, clearly fake records, including a known login for local use.
3. Give the one-command start (docker compose up --wait or a make dev / script wrapper), plus reset, logs, shell and test commands.
4. List every remaining difference from production and its consequence, and a short troubleshooting section (port in use, CPU architecture mismatches on ARM machines, stale volumes, file-watching on mounted folders).

If a service's build or start command is unknown and the repository is not available, ask for it rather than inventing one.

• Every image is pinned. Every dependency has a health check. Every data store has a named volume.
• No secrets, tokens or real personal data in any file. Local passwords are obviously local (for example localdev).
• Do not add services that were not asked for, except a local stand-in for a dependency that has none; say why each was added.
• Keep it runnable on macOS, Linux and Windows with WSL; call out anything that is not.
• Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
• If you could not run a check, say so plainly and say which one.

Assumptions

Bullets, only those that shaped the setup.

compose.yaml

One yaml code block, with short comments on non-obvious lines.

.env.example

One code block.

Seed data

The seed scripts or seed service, and what records they create.

Commands

A table: task | command. Include start, stop, reset data, logs, shell, run tests.

Differences from production

Table: area | production | local | consequence.

Troubleshooting

Short bullets: symptom, then fix.