Qvantor logo QvantorInfrastructure, explained plainly
Dev Tools

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.

Laptop on a standing desk showing a terminal with several running containers next to a coffee mug and a notebook

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.

CommandContainersVolumesTypical use
docker compose stopStopped, keptKeptEnd of the day
docker compose downRemovedKeptAfter changing the compose file
docker compose down -vRemovedRemovedClean slate before testing migrations
docker compose up -d with the build flagRebuiltKeptAfter 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:

  1. Pin every image to a specific tag such as postgres:16.4, never latest. Upgrade on purpose, in its own pull request.
  2. 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.
  3. 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.
  4. 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.

IV
Ilkka Varis

Ilkka has run mail servers for small companies since the days of hand edited DNS zones.

More posts by Ilkka

More in Dev Tools

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr webtech1223411 wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto