Docker Compose for Local Development on a Small Project
A new developer joins, clones the repo, and spends the whole afternoon installing the right Postgres version, finding a Redis binary that runs on their laptop, and asking which port the mail catcher uses.

A new developer joins, clones the repo, and spends the whole afternoon installing the right Postgres version, finding a Redis binary that runs on their laptop, and asking which port the mail catcher uses. By the time the app starts, nobody remembers which steps actually mattered. Docker Compose for local development fixes that by putting every supporting service in one file that starts with one command, so day one becomes a twenty minute job instead of a lost afternoon.
This guide walks through a working setup for a small web project: one app, one database, one cache and a fake mail server. It also covers the parts that usually go wrong, like slow file mounts on macOS, data that vanishes between restarts, and containers that start before the database is ready.
What Docker Compose for local development actually solves
Compose is not a deployment tool for most small teams, and it does not need to be. Its job on a laptop is narrower: describe the services your code depends on, pin their versions, and start or stop them together. A typical project ends up with a file of about 40 lines that replaces a page of setup notes nobody keeps current.
The concrete wins are easy to measure. Postgres 16.4 runs on everyone's machine, not a mix of 14, 15 and whatever Homebrew installed last spring. Port numbers live in one place. Tearing everything down and starting fresh takes about 10 seconds, which makes testing a migration from an empty database a habit instead of a chore. If your team has fought the slow gap described in how a local setup drifts away from production, pinned service versions close most of it.
A small compose file that works on day one
Create a file named compose.yaml at the root of the repository. The older docker-compose.yml name still works, but current versions of Docker look for compose.yaml first. A sensible starting layout has four services:
- db: image postgres:16.4, port 5432 mapped to 5432 on the host, a named volume for /var/lib/postgresql/data, and POSTGRES_PASSWORD set from an environment variable.
- cache: image redis:7.2-alpine, port 6379, no volume, because losing cache data on restart is fine.
- mail: image axllent/mailpit, ports 1025 for SMTP and 8025 for the web inbox, so password reset emails land somewhere you can read them.
- app: built from your own Dockerfile, with the source folder mounted and a depends_on entry pointing at db and cache.
Start everything with docker compose up -d, check status with docker compose ps, and follow logs from one service with docker compose logs -f app. Those three commands cover about 90 percent of daily use.
Keep secrets out of the file itself. Compose reads a .env file in the same folder automatically, so the YAML can say POSTGRES_PASSWORD: ${DB_PASSWORD} while the real value sits in .env, which stays in .gitignore. Commit a .env.example with harmless values so a new clone works after one copy command. If you already load variables per folder, the approach in setting up direnv for per project environment variables fits alongside this without conflict.
Wait for the database properly
A plain depends_on only waits for the database container to start, not for Postgres to accept connections. On a cold machine that gap can be 3 to 8 seconds, long enough for your app to crash on boot. Add a healthcheck to the db service that runs pg_isready -U postgres every 2 seconds with 10 retries, then change the app's dependency to condition: service_healthy. The app now waits until the database answers, and the random first-run failures stop.
Volumes, data and the reset button
Named volumes keep your database between restarts. Running docker compose down stops and removes containers but leaves volumes alone, so your test data survives. Running docker compose down -v removes the volumes too, which gives you a completely empty database. Teach the team both, because confusing them is the most common cause of "where did my data go" messages.
A good habit is a seed script that rebuilds useful sample data in under a minute. Wrap the reset in a single task so nobody has to remember the order. A make target that runs down -v, up -d, waits for health, runs migrations and loads seed data is about six lines. The patterns in this Makefile task runner setup for small projects work well here.
| Command | Containers | Volumes | Typical use |
|---|---|---|---|
| docker compose stop | Stopped, kept | Kept | End of the day |
| docker compose down | Removed | Kept | After changing the compose file |
| docker compose down -v | Removed | Removed | Clean slate before testing migrations |
| docker compose up -d with the build flag | Rebuilt | Kept | After changing the Dockerfile |
Why you should not put the app itself in a container at first
Most tutorials containerize everything, including the application you are actively editing. For a small team that is often the wrong first move. Bind mounts on macOS and Windows still add noticeable lag to file watchers, and a Node or Python project with 30,000 files in its dependency folder can make hot reload take 2 to 4 seconds instead of near instant. Debuggers need extra port wiring. Editor tooling like linters and type checkers wants the dependencies installed locally anyway.
A calmer split is to run databases, caches, queues and mail catchers in Compose, and run the app directly on the host with its normal dev server. You get pinned versions for the parts that are painful to install and native speed for the part you touch every minute. When the app has system dependencies that are truly hard to install, such as a specific ImageMagick build or an old PDF library, move it into Compose then and accept the trade. Start with the services, not the app.
If you do containerize the app, mount the source folder but keep the dependency folder inside the container with an anonymous volume. That one line stops the host's node_modules or .venv from overwriting the container's copy, which avoids a whole class of "works on my machine" errors caused by binaries compiled for the wrong operating system.
Keeping the setup healthy over months
Compose files rot quietly. Someone adds a service for a spike, never removes it, and six months later everyone downloads a 900 MB image they never use. A few low-effort rules keep things tidy:
- Pin every image to a specific tag such as postgres:16.4, never latest. Upgrade on purpose, in its own pull request.
- Use profiles for optional services. A search engine or a metrics stack can sit behind profiles: ["extras"] so it only starts when someone asks for it.
- Run docker system df once a month. Old images and build cache can quietly reach 20 to 40 GB on a busy laptop, and docker system prune clears most of it.
- Match the production database major version. If production runs Postgres 16, local runs 16, even if 17 is out.
Review the file whenever you add a dependency to production. If the two lists drift apart, the local setup stops telling you the truth.
Frequently asked questions
Is Docker Compose good for local development?
Yes, especially for the services your code depends on, like databases, caches and mail servers. It pins versions and starts everything with one command. Running the app itself in a container is optional and sometimes slower on macOS and Windows.
What is the difference between docker compose down and down -v?
docker compose down removes the containers and network but keeps named volumes, so your database data survives. Adding -v removes the volumes as well, which wipes stored data. Use -v only when you want a truly empty start.
Should compose.yaml be committed to Git?
Yes, the compose file should live in the repository so every developer runs the same services. Keep passwords and tokens in a .env file that is ignored by Git, and commit a .env.example with safe placeholder values instead.
More in Dev Tools
Dev Tools
Git includeIf Setup for Work and Personal Identities
The commit that made me fix this properly had my personal address on it, sitting in a client repository, pushed to a branch...
Dev Tools
Sign Git Commits With an SSH Key in Fifteen Minutes
Anyone can set their Git name and email to yours. It takes one line of config, no password and no access to your accounts, and...
Dev Tools
Git Bisect to Find the Commit That Broke Your Build
The build passed on Monday and fails on Thursday, and there are 140 commits in between.