Docker for Development: One Command to a Working App
A docker development environment has two jobs: one-command onboarding and a fast inner loop. What to containerize, what to keep native, and how to test both.
A new engineer's first day tells you more about your docker development environment than any architecture diagram. If they can clone the repo, run one command and see the app working before lunch, the setup is doing its job. If they spend two days on a wiki page of install steps and database version mismatches, it isn't, no matter how many containers you have.
I treat Docker in development as a productivity and onboarding decision, not a DevOps hobby. It has two jobs, and they pull in opposite directions. Here's how I'd set it up today, what I'd leave out of the container, and how to check that it's still working six months from now.
# The two jobs of a Docker development environment
Job one is onboarding. Understanding a codebase already takes long enough (it can take months to get there); getting the code to run shouldn't add days on top. Every hire, every new laptop and every contractor pays the setup cost again. A reproducible environment turns that cost into one command.
Job two is the inner loop: edit, save, see the result. It's the loop developers run hundreds of times a day, and I've written before about where inner-loop time disappears. A setup that adds a few seconds to every save can quietly cost more over a year than one that takes an extra hour to install once.
Here's the tension. Containers make onboarding reproducible. They can also put a virtualized file system and an image build between your keyboard and your running code. Every decision below is about getting the first benefit without paying for it in the second.
# The contrarian take: don't containerize the app by default
This one annoys platform teams. For a lot of teams, the best Docker development setup runs the app natively and containerizes only its dependencies: Postgres, Redis, a message queue, a stand-in for S3 or email. Those are the parts that are painful to install, sensitive to versions and identical for every developer. Your app code is the part you edit all day, and it's the part that suffers most from a file-sync layer.
Running the app on the host keeps the debugger, the language server, test watchers and hot reload exactly as fast as they are without Docker. You keep the onboarding win, because docker compose up --wait starts every dependency and waits until they report healthy. What's left is a runtime version file (.nvmrc, .tool-versions or .python-version) and an install command, which a make dev target can wrap.
Figure 1. Keep the code you edit on the host and put the hard-to-install dependencies in Compose.
Containerize the app as well when the runtime itself is the hard part: native extensions that need system libraries, several services in different languages, or a toolchain that behaves differently enough on macOS, Windows and Linux to produce "works on my machine" bugs. Those are real reasons. "Everything should be in Docker" isn't one.
# Compose for dependencies, with healthchecks that mean something
Whichever way the app runs, the dependencies belong in a Compose file. Drop the top-level version: key while you're there: the Compose file reference marks it obsolete and Compose warns when it sees it. Then make startup order real. By default Compose waits only until a dependency's container is running, not until the service inside it is ready, so on a cold start your app races Postgres and loses.[1]
condition: service_healthy holds the app back until pg_isready succeeds. The doubled $$ stops Compose from interpolating the variables itself, so the shell inside the container expands them. If you run the app natively, delete the app service and nothing else changes: docker compose up --wait now starts Postgres and returns once it's healthy, which also makes it a clean readiness gate for scripts and CI.
If you do containerize the app, don't maintain a separate Dockerfile.dev that drifts away from production. Use one multi-stage Dockerfile and point Compose at a dev stage with build.target, as the file above does. Docker's multi-stage docs describe this pattern directly: you don't have to build every stage, and a debug stage with extra tooling can sit next to a lean production stage.[2]
dockerfile
# syntax=docker/dockerfile:1FROM node:24-alpine AS baseWORKDIR /appRUN chown node:node /appUSER nodeCOPY --chown=node:node package.json package-lock.json ./RUN --mount=type=cache,target=/home/node/.npm,uid=1000,gid=1000 npm ciFROM base AS devCOPY --chown=node:node . .CMD ["npm", "run", "dev"]FROM base AS buildCOPY --chown=node:node . .RUN npm run buildFROM node:24-alpine AS prodWORKDIR /appENV NODE_ENV=productionCOPY package.json package-lock.json ./RUN --mount=type=cache,target=/root/.npm npm ci --omit=devCOPY --from=build /app/dist ./distUSER nodeCMD ["node", "dist/server.js"]
The order of the first few lines is the whole caching story. Copy the lockfile, install, then copy the source. Docker's build cache guide makes the same point: split the COPY so that editing a source file doesn't invalidate the install layer. The --mount=type=cache line keeps npm's download cache between builds, so when the lockfile does change, packages you already had aren't downloaded again. The uid and gid options hand that cache to the image's node user (uid 1000), because everything from the install onward runs as node, not root, and the dev server can write wherever it needs to under /app.[3]
Add a .dockerignore that lists node_modules. Without it, COPY . . drags your host's node_modules into the image, native modules compiled for the wrong OS included.
This is where the inner loop is won or lost. The classic setup bind-mounts the whole project into the container and hides node_modules behind an anonymous volume. It works, but every file the dev server reads crosses the boundary between your machine and the container, and the anonymous-volume trick is easy to get wrong.
Compose Watch is the newer option. You declare rules under develop.watch on a service that has a build section, then run docker compose up --watch, or docker compose watch if you want build and sync output kept out of your app logs. Each rule names a path and an action:
sync copies changed files into the running container at target. Your dev server's own hot reload does the rest.
rebuild builds a new image and replaces the container. Point it at the lockfile.
sync+restart syncs, then restarts the container, for config files a process reads once at startup.
restart and sync+exec cover restart-only and run-a-command-after-sync cases in Compose 2.32.0 and later.
Docker's own docs call Watch a companion to bind mounts, not a replacement. They give two reasons to prefer it for source code: file trees with many small files can cause high I/O load in some configurations, and compiled artifacts such as native npm modules can't be shared when the host OS or architecture differs from the container. With Watch you sync src/ and never sync node_modules at all.[4]
Figure 2. Sync handles the edits you make all day; rebuild is reserved for dependency changes.
The same docs list three gotchas. The image needs stat, mkdir and rmdir. The container's user must be able to write to the target path, which is why the Dockerfile uses COPY --chown. And Watch only applies to services built from a build section, not to prebuilt images.
With Docker Engine on Linux, a bind mount costs almost nothing. Docker Desktop runs containers inside a VM, so files cross a boundary. On Windows with WSL 2, Docker's guidance is direct: keep bind-mounted source in the Linux filesystem rather than under /mnt/c, because performance is much higher there and Linux containers only receive file change events when the files live on the Linux side. Cloning into your WSL home directory fixes a lot of "hot reload never fires" complaints.[5]
On macOS, Docker Desktop shares files through VirtioFS or gRPC FUSE. For very large repositories, Docker offers synchronized file shares, aimed at codebases of 100,000 files or more where those file systems stop scaling. If you're in that range, time the inner loop on your own repo before and after switching.[6]
The Dev Containers spec goes one step further. A .devcontainer/devcontainer.json file describes a container that the editor itself runs inside: language server, extensions, terminal and all. Visual Studio Code, IntelliJ IDEA, the Dev Container CLI and GitHub Codespaces are among the tools that read it. With Compose, two properties are required: dockerComposeFile, a path relative to devcontainer.json, and service, the container the editor attaches to.[7]
The containers.dev guide pairs this with a Compose file next to it that bind-mounts the workspace and runs sleep infinity, so the editor has a long-running container to attach to:
That's the trade-off. Dev Containers put everyone on an identical toolchain, but they lean on bind mounts, so the macOS and Windows caveats above apply in full. My rule: reach for them when the toolchain is the hard part, or when you want cloud environments such as Codespaces. For a typical web app with one runtime, they're more machinery than you need.
Toolchain is the hard part, or cloud dev environments
devcontainer.json
# Measure it: the onboarding test and the inner-loop test
A dev environment rots quietly. Somebody adds a service, a migration step, an environment variable that only exists on their laptop. Two checks catch it.
Once a quarter, someone on a clean machine, ideally the newest hire, clones the repo and runs exactly one command: docker compose up --watch, or a make dev that wraps docker compose up --wait and the native install. Success means the app answering on localhost with seed data. Every manual step they hit becomes a bug in the tracker, not a new line in the README.
Time the loops people actually run. Three numbers are enough: cold start (docker compose up to first successful request), warm edit (save to reload) and dependency change (lockfile edit to working app). A small script keeps the first one honest:
Cold start matters for onboarding. Warm edit matters hundreds of times a day. Dependency change matters every week or two. The same logic applies as with build times: small delays repeated all day are the expensive ones. If warm edit inside the container is clearly slower than running the app natively, that's your signal to move the app out of Docker and keep the dependencies in.
A docker development environment has two jobs: one-command onboarding and a fast inner loop. Judge every choice against both.
Containerize dependencies always. Containerize the app only when its runtime or toolchain is the hard part.
Use healthchecks with condition: service_healthy, and docker compose up --wait as the readiness gate.
Prefer Compose Watch for source code: sync for files the dev server reloads, rebuild for the lockfile, and never sync node_modules.
Run the onboarding test every quarter and time warm edits, or the setup will drift without anyone noticing.
Run the onboarding test this week. If a new hire can't get from clone to working app with one command, fix that before anyone argues about bind mounts.
Frequently asked questions
Is Compose Watch better than bind mounts for local development?
For source code in a containerized app, usually yes. Watch syncs only the paths you list, so you can skip node_modules and avoid native modules built for the wrong OS. Bind mounts are still the right tool when the editor runs inside the container, as with Dev Containers, and with Docker Engine on Linux they cost almost nothing.
Why does my app start before the database is ready in Docker Compose?
By default Compose waits only until a dependency's container is running, not until the service inside it is ready. Add a healthcheck to the database, such as pg_isready for Postgres, and declare the dependency with condition: service_healthy. Compose then holds the app back until the check passes.
Should I run my app inside Docker during development?
Only when the runtime is the hard part: native extensions that need system libraries, several services in different languages, or a toolchain that behaves differently across operating systems. Otherwise run the app natively and keep databases, caches and queues in Compose. You keep one-command onboarding without file sync between your editor and your code.
When should I use Dev Containers instead of plain Docker Compose?
Use Dev Containers when the toolchain itself is hard to install, or when you want cloud environments such as GitHub Codespaces. The editor then runs inside the container, which needs a bind-mounted workspace. For a typical web app with one runtime, Compose for the dependencies plus a native app is simpler.
Small frictions cost more than big blockers. 47 micro-frictions consume 96 minutes per engineer per day. Here's the TAX Return framework for finding and eliminating the developer productivity tax.
Engineers spend 38% of their time on repetitive, automatable work. Here's a toil audit process that identifies where time disappears and a framework for systematic elimination with measurable ROI.
Developer experience is a systems design problem, not a culture problem. Platform engineering reduces cognitive load from 12 concepts to 3 for common tasks. Here's the LOAD assessment framework.
The 10x developer myth is actively harmful to engineering teams. After tracking individual metrics vs team output, I found that the highest performers often had negative correlations with team throughput.
30-45% of engineering time produces zero customer value. Here's a 4-week audit process that identifies exactly where time goes and the AUDIT cadence for continuous productivity improvement.
Sprint velocity measures estimation consistency, not productivity. After tracking 8 teams, I found velocity often increases while actual output declines. Here's the SHIP framework that replaces it.