Skip to content

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.

11 min read
Modular unmarked enclosures connect through teal fittings, with one open to show its contained mechanism.
On this page

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.

One command: docker compose up --wait Your machine, native app process debugger + language server test watcher, hot reload the code you edit all day Docker Compose Postgres + healthcheck Redis or a queue S3 or email stand-in installed once, same for everyone
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]

yaml
# compose.yaml
services:
  app:
    build:
      context: .
      target: dev
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package-lock.json

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pgdata:

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.

A multi-stage Dockerfile with a dev target

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:1
FROM node:24-alpine AS base
WORKDIR /app
RUN chown node:node /app
USER node
COPY --chown=node:node package.json package-lock.json ./
RUN --mount=type=cache,target=/home/node/.npm,uid=1000,gid=1000 npm ci

FROM base AS dev
COPY --chown=node:node . .
CMD ["npm", "run", "dev"]

FROM base AS build
COPY --chown=node:node . .
RUN npm run build

FROM node:24-alpine AS prod
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["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.

Compose Watch vs bind mounts

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]

docker compose up --watch action: sync · files in src/ src/ file saved sync to /app/src dev server reloads container keeps running, its hot reload does the rest action: rebuild · package-lock.json lockfile changes rebuild image container replaced new image with BuildKit, then a new container
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.

File sync performance on macOS and Windows

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]

Dev Containers: when the editor moves in too

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]

json
{
  "name": "app",
  "dockerComposeFile": "compose.yaml",
  "service": "devcontainer",
  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
  "forwardPorts": [3000],
  "postCreateCommand": "npm ci"
}

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:

yaml
# .devcontainer/compose.yaml
services:
  devcontainer:
    build:
      context: ..
      target: dev
    volumes:
      - ../..:/workspaces:cached
    command: sleep infinity

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.

The decision table: what to put in Docker

Component My default Change it when How
Database, cache, queue Compose, always Never Healthcheck plus condition: service_healthy
Third-party stand-ins (S3, email) Compose A shared cloud sandbox is good enough Same Compose file, no ports you don't need
App runtime, one language Native, version pinned System libraries or OS-specific bugs Dev stage in one multi-stage Dockerfile
Several services, mixed languages Compose with Watch One service is edited far more than the rest Run that one natively
Source code into a container Watch sync The editor lives in the container Bind mount, source on the Linux side
Dependency changes Watch rebuild on the lockfile Installs are slow even when cached Cache mount, lockfile copied first
Editor and toolchain Native 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.

The onboarding test

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.

The inner-loop test

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:

bash
#!/usr/bin/env bash
set -euo pipefail
start=$(date +%s)
docker compose up --build --wait
until curl -fsS http://localhost:3000/ > /dev/null; do sleep 1; done
echo "cold start: $(( $(date +%s) - start ))s"

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.

Key takeaways

  • 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.

Sources

  1. [1]Control startup and shutdown order in Compose · Docker Docs
  2. [2]Multi-stage builds · Docker Docs
  3. [3]Optimize cache usage in builds · Docker Docs
  4. [4]Use Compose Watch · Docker Docs
  5. [5]WSL 2 best practices for Docker Desktop on Windows · Docker Docs
  6. [6]Synchronized file shares · Docker Docs
  7. [7]Dev Container metadata reference · Development Containers (containers.dev)

Checked against these sources on

Related Articles