🐳 Development Workflows with Docker

Docker Beyond Production

Most people meet Docker as a deployment tool: build an image, ship it, run it in the cloud. But the same property that makes it good at deployment — a reproducible, self-contained environment — makes it just as valuable while you're writing the code. When your database, your exact Node version, and your OS libraries all live inside containers described by files in your repo, every developer runs the same stack, and that stack looks a lot like production.

Concretely, running your dev stack in containers buys you:

• Consistency — one Node version, one Postgres version, for the whole team, on any OS.
• Isolation — project A's dependencies can't collide with project B's, and nothing pollutes your host machine.
• Fast onboarding — git clone then docker compose up, and a new hire is productive in minutes instead of a day of README archaeology.
• Production parity — deployment surprises shrink because dev and prod share the same base images.
• Disposability — break things freely; docker compose down -v resets you to a clean slate.

Four Workflow Patterns

There's a spectrum of how tightly you couple Docker to your inner loop. Knowing the four common patterns helps you pick the right one for the project in front of you.

Pattern 1 — Build and Run

The simplest loop: rebuild the image on every change. Fine for a demo or a quick smoke test, painfully slow for real work because each edit means a full docker build.

docker build -t my-app .
docker run -p 3000:3000 my-app
# edit code → stop → rebuild → run again  (slow!)

Pattern 2 — Bind-Mount for live edits

Mount your source directory into the container so the code the container runs is the code on your disk. Edit in your editor, the change is instantly visible inside the container. This is the workhorse pattern for interpreted stacks like Node.js, and the one we'll build on for the rest of the lesson.

Pattern 3 — Compose multi-service

Real apps aren't one process. Docker Compose declares your app plus its database, cache, and message queue in a single file and starts them together on a shared network. This is where Docker development earns its keep.

Pattern 4 — Dev Containers

Your editor (VS Code with the Dev Containers extension) attaches to a running container, so your terminal, linter, and language server all execute inside the same environment your app runs in. Maximum parity, slightly more setup.

A Development Dockerfile

A dev image and a prod image have different jobs. Production wants a small, locked-down image with only what's needed to run. Development wants your dev dependencies, a hot-reloading start command, and a build that rebuilds quickly when only your source changes.

The single most important trick is layer ordering: copy package*.json and install dependencies before copying the rest of your source. Docker caches each layer, so as long as your dependencies haven't changed, edits to your app code skip the slow npm install entirely.

# Dockerfile.dev — optimized for the inner loop
FROM node:20-alpine

WORKDIR /app

# 1. Copy ONLY the manifest first. This layer is cached and reused
#    on every rebuild where package.json/package-lock.json are unchanged.
COPY package*.json ./

# 2. Install ALL dependencies, including devDependencies (nodemon, etc.)
RUN npm ci

# 3. Copy the source last, so editing code doesn't bust the deps layer.
COPY . .

# 4. The dev server port
EXPOSE 3000

# 5. Start a watcher, not "node index.js" — we want restarts on change
CMD ["npm", "run", "dev"]

Pair it with a .dockerignore so your host's node_modules and git history never get copied into the build context (which would be slow and could clobber the container's own modules):

# .dockerignore
node_modules
npm-debug.log
.git
.env
.env.local
dist
build
coverage

Dev vs Prod: compose.override.yaml

Modern Compose (the docker compose v2 plugin) reads two files automatically when you run docker compose up: the base compose.yaml and, if present, compose.override.yaml. The override is deep-merged on top of the base. This gives you a clean split: shared truth in the base file, dev-only conveniences in the override, and a separate explicit file for production.

Base — compose.yaml (shared truth)

# compose.yaml — what dev and prod agree on
services:
  api:
    build:
      context: .
    environment:
      NODE_ENV: production
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  db_data:

Override — compose.override.yaml (dev only, auto-loaded)

# compose.override.yaml — merged on top automatically in dev
services:
  api:
    build:
      dockerfile: Dockerfile.dev   # use the dev image instead
    environment:
      NODE_ENV: development        # override the base value
    volumes:
      - ./:/app                    # bind-mount source for live edits
      - /app/node_modules          # keep the container's node_modules
    command: npm run dev           # hot-reload start command

Production — explicit, never auto-loaded

# Dev: base + override merge automatically
docker compose up

# Prod: name the files explicitly so the override is NOT applied
docker compose -f compose.yaml -f compose.prod.yaml up -d

Bind Mounts & the node_modules Trap

A bind mount maps a host directory into the container: ./:/app means "the container's /app is my project folder." Edit a file on your laptop and the container sees it immediately — that's what makes live editing possible. But there's a classic gotcha.

When you bind-mount ./ onto /app, your host's project folder replaces the container's /app — including the node_modules the image installed during docker build. If your host has no node_modules (or has ones built for a different OS/architecture), the app breaks with "module not found" or native-binary errors.

The fix is a second, anonymous volume layered on top of the bind mount, aimed precisely at node_modules:

volumes:
  - ./:/app              # bind-mount your source (live edits)
  - /app/node_modules    # anonymous volume: shields the container's own modules

Because the more specific path (/app/node_modules) wins, the container keeps the node_modules it installed at build time, while everything else in /app comes live from your host. Best of both worlds.

The Daily Command Loop

Once your Compose files exist, day-to-day development is a handful of commands. These are the ones you'll type dozens of times a day.

# Start everything (foreground; Ctrl+C to stop)
docker compose up

# Start in the background instead
docker compose up -d

# Rebuild images (after changing a Dockerfile or dependencies)
docker compose up --build

# Follow logs for one service in real time
docker compose logs -f api

# Open a shell inside a running container
docker compose exec api sh

# Run a one-off command (install a package, run a migration)
docker compose exec api npm install zod
docker compose exec api npm run migrate

# Run a throwaway command in a fresh container, then remove it
docker compose run --rm api npm test

# Stop and remove containers (keep named volumes / data)
docker compose down

# Stop AND wipe volumes for a truly clean slate
docker compose down -v

$ docker compose up
[+] Running 2/2
 ✔ Container app-db-1   Healthy    5.1s
 ✔ Container app-api-1  Started    5.3s
app-api-1  | Server listening on http://0.0.0.0:3000
app-api-1  | Connected to postgres at db:5432

Healthchecks & Startup Order

depends_on alone only waits for a container to start, not to be ready. Your API might launch and try to connect to Postgres before Postgres has finished initializing, and crash. A healthcheck plus condition: service_healthy makes Compose wait for genuine readiness.

services:
  api:
    # ...
    depends_on:
      db:
        condition: service_healthy   # wait until db's healthcheck passes

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s      # how often to run the check
      timeout: 3s       # how long each check may take
      retries: 5        # failures allowed before "unhealthy"
      start_period: 10s # grace window on first boot

You can healthcheck your own app too. Add a tiny endpoint and point Compose at it:

  api:
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 15s

// A minimal health endpoint (Express)
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', uptime: process.uptime() });
});

Practice & Quiz

# compose.override.yaml
services:
  api:
    build:
      dockerfile: Dockerfile.dev
    environment:
      NODE_ENV: development
    volumes:
      - ./:/app
      - /app/node_modules
    command: npm run dev

# Wrong (inside a container)
postgres://postgres:secret@localhost:5432/appdb
# Right — "db" is the service name from compose.yaml
postgres://postgres:secret@db:5432/appdb

Best Practices & Pitfalls

✅ Do

• Copy package*.json and install before copying source, to keep the dependency layer cached
• Keep shared config in compose.yaml; put dev-only conveniences in compose.override.yaml
• Protect the container's node_modules with an anonymous volume
• Reference other services by their Compose service name, never localhost
• Add healthchecks so services start in the right order
• Commit all Docker config to version control so onboarding is one command

❌ Don't

• Bake secrets into images — pass them via environment or an .env file that's git-ignored
• Rely on compose.override.yaml loading in CI or prod — pass -f explicitly there
• Bind-mount your whole tree on macOS/Windows if performance suffers — mount only ./src
• Leave the obsolete version: key in new Compose files
• Assume depends_on means "wait until ready" — it doesn't without a healthcheck

Summary

📚 Additional Resources

• Docker Docs — Merge Compose files
• Docker Docs — Dockerfile best practices
• Docker Docs — depends_on & healthchecks
• Docker Docs — Bind mounts

🚀 What's Next?

Your bind-mount is delivering fresh code into the container, but the process inside still needs to notice and restart. The next lesson wires up Hot Reloading in Containers — nodemon, Vite --host, and the CHOKIDAR_USEPOLLING flag that rescues file-watching on tricky mounts.