Skip to content
Tutorials Center
My learning

Topics

Lesson 63 of 111 ยท Docker Compose

Compose for Development

Set up a fast Compose dev loop: bind-mount your code, protect node_modules, use compose watch with sync and rebuild, run one-off commands, and avoid file-event pitfalls.

Compose is at its best as a development tool. One command gives every developer the same database, cache and runtime versions, with none of it installed on their laptop. But a good dev setup has one extra requirement that production does not: when you save a file, you want to see the change in seconds, without rebuilding an image each time.

This lesson builds that loop step by step with a tiny Node.js server: bind-mounting source code, the node_modules trap, the file-event pitfall on Windows and macOS, Compose's built-in watch mode, and the commands for one-off tasks. The ideas apply to any language. Everything was run on Docker 29 with Compose v5 on Docker Desktop for Windows. For the underlying mount types, see Bind Mounts.

The sample project

Our app is three small files plus a Dockerfile. src/server.js answers every request with a message from src/message.js:

JavaScript
const http = require('http');
const message = require('./message');
http.createServer((req, res) => res.end(message() + '\n')).listen(3000, () => console.log('listening on 3000'));
JavaScript
module.exports = () => 'hello v1';
DOCKERFILE
FROM node:lts-alpine
WORKDIR /app
COPY package.json ./
COPY src ./src
CMD ["node", "src/server.js"]

The package.json has no dependencies; it only names the project. The image bakes the code in with COPY, which is exactly what you want for production. For development, baking in code means a rebuild after every edit, so we need a different approach.

Approach 1: bind-mount the source

A bind mount replaces the image's /app/src with your real folder, so edits appear in the container instantly:

YAML
name: tcd-b9-dev
services:
  web:
    build: .
    image: tcd-b9-dev-web
    command: ["npm", "run", "dev"]
    ports:
      - "127.0.0.1:18092:3000"
    volumes:
      - ./src:/app/src

Here command overrides the image's CMD with a development command: npm run dev runs node --watch src/server.js, which restarts the server when its files change. This is the classic setup, and on a Linux machine it just works. Our first run confirms the app answers:

CONSOLE
$ docker compose up -d --build
$ curl -s localhost:18092
hello v1

The pitfall: file events may not cross the mount

Now edit src/message.js on the host to say hello v2, wait a few seconds, and ask again:

CONSOLE
$ curl -s localhost:18092
hello v1

Still v1. The file did change inside the container (a restart proves it), but node --watch never noticed:

CONSOLE
$ docker compose restart web
$ curl -s localhost:18092
hello v2

The cause is how file watching works. Tools like node --watch, nodemon and webpack rely on inotify events from the kernel. When you edit a file on Windows or macOS, the change happens in the host's filesystem, and Docker Desktop shares it into its Linux VM; the events do not always arrive. On a native Linux host they do. Different tools offer a "polling" option as a workaround (nodemon's --legacy-watch, webpack's watchOptions.poll), but polling burns CPU and is slow on big projects. Compose has a better answer.

Whether bind-mount events work depends on your OS, Docker Desktop version and file-sharing backend. Do not assume either way: test your own setup once by editing a file and watching the logs.

Approach 2: compose watch

Compose can watch the files itself, on the host, and push changes into the container. You describe this with a develop.watch section:

YAML
name: tcd-b9-dev
services:
  web:
    build: .
    image: tcd-b9-dev-web
    command: ["node", "--watch", "src/server.js"]
    ports:
      - "127.0.0.1:18092:3000"
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

Each rule has an action and a path to watch:

Action What Compose does when files change Use for
sync Copies the changed files into the running container Source code for hot-reload tools
sync+restart Copies the files, then restarts the container Config files and servers without a reloader
sync+exec Copies the files, then runs a command in the container Custom reload hooks
rebuild Rebuilds the image and recreates the container package.json, lock files, the Dockerfile

Start it with up --watch (or run docker compose watch, which also starts the services):

CONSOLE
$ docker compose up --build --watch
        โฆฟ Watch enabled
web-1   | listening on 3000

Now edit message.js to say hello v4:

CONSOLE
        โฆฟ Syncing service "web" after 1 changes were detected
web-1   | Restarting 'src/server.js'
web-1   | listening on 3000
$ curl -s localhost:18092
hello v4

It worked, and no container restart was needed from Compose: sync wrote the file inside the container, so the kernel there produced a normal inotify event and node --watch restarted the server itself. This combination, Compose watch sync plus the language's own reloader, gives hot reload on every platform.

When the dependency list changes, a rebuild rule handles it. After editing package.json:

CONSOLE
        โฆฟ Rebuilding service(s) ["web"] after changes were detected...
 Image tcd-b9-dev-web Built
        โฆฟ service(s) ["web"] successfully built
 Container tcd-b9-dev-web-1 Recreate
 Container tcd-b9-dev-web-1 Started
web-1   | listening on 3000

Compose rebuilt the image (with the build cache doing its job; see The Build Cache) and replaced the container. Only the change that really needs a rebuild pays that cost.

Two options refine the rules. ignore skips paths (such as node_modules/ or *.log), and initial_sync: true on a sync rule copies the files once when watch starts. Also note that develop.watch has no effect on a plain docker compose up; the rules only apply when you start watch mode.

Watch mode copies files into the container, so edits made inside the container do not flow back to your project. That one-way flow is a feature: your source of truth stays on the host.

The node_modules trap

If you mount your entire project folder over the app folder, you hide whatever the image put there, including dependencies installed during the build. We can reproduce this with a Dockerfile that creates /app/node_modules/marker and two services:

YAML
name: tcd-b9-nm
services:
  hidden:
    build: .
    image: tcd-b9-nm-img
    volumes:
      - ./code:/app
  kept:
    image: tcd-b9-nm-img
    volumes:
      - ./code:/app
      - /app/node_modules

Both run ls /app; cat /app/node_modules/marker:

CONSOLE
$ docker compose up
hidden-1  | app.txt
hidden-1  | cat: can't open '/app/node_modules/marker': No such file or directory
kept-1    | app.txt
kept-1    | node_modules
kept-1    | installed-in-image

In hidden the bind mount covers all of /app, so the installed dependency is gone. In kept, the extra line - /app/node_modules mounts an anonymous volume at that path, which Docker fills from the image first; since it is more specific, it shows through the bind mount. The same pattern protects vendor/ in PHP, .venv in Python or target/ in Rust. It also keeps Linux binaries from the image away from your Windows or macOS ones.

(You may notice an empty node_modules folder appear in your project. Docker creates the mount point on the host. Add it to .gitignore.)

One-off commands in the dev stack

Development is more than starting servers. You also run migrations, tests, linters and REPLs. Compose has two commands for this:

  • docker compose exec web <cmd> runs a command inside an already running container.
  • docker compose run --rm web <cmd> starts a new, temporary container from the service definition, with its mounts, networks and environment, then removes it.
CONSOLE
$ docker compose run --rm web node -e 'console.log(process.version)'
v24.22.1

run also starts the service's dependencies, so a test command that needs the database brings the database up. Add --no-deps to prevent that. Use run for tasks that should not touch the live container (tests, migrations, scripts), and exec to look inside it (shell, debugging). More in Compose Commands.

docker compose run does not publish the service's ports by default (to avoid clashing with the running container). Add --service-ports if you really need them.

Dev versus production in one file?

Development wants bind mounts, a reloader command and debug ports. Production wants a baked image, no mounts and a restart policy. Packing both into one file with comments gets confusing fast. The clean solution is a base compose.yaml plus an override file for each environment. Compose even reads compose.override.yaml automatically. You will set that up in Multiple Files, Profiles and Extends.

A dev workflow checklist

  1. Put source code under a bind mount or a develop.watch rule, not both for the same path.
  2. Use the language's own reloader inside the container (node --watch, uvicorn --reload, air for Go) and let sync feed it.
  3. Use rebuild for dependency manifests, so dependencies stay in the image.
  4. Protect installed dependency folders with an anonymous volume if you bind-mount the whole project.
  5. Publish ports to 127.0.0.1 only, so your dev server is not exposed to the network (Publishing Ports).
  6. Keep a .dockerignore so the build context stays small (Build Context and .dockerignore).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You bind-mount ./src into a container on Docker Desktop for Windows, but node --watch does not restart when you save a file. What is the likely cause?

    File watchers rely on inotify events. Changes made on the host side of a Docker Desktop file share may not produce them, even though the content is updated.
  2. 2. Which develop.watch action copies changed files into the running container without restarting it?

    sync only copies. With a reloader running inside the container, the copy triggers a normal inotify event there.
  3. 3. When should a watch rule use action: rebuild?

    Dependencies and build instructions live in the image, so changing them needs a rebuild and a new container.
  4. 4. What does the extra volume line - /app/node_modules achieve in the compose file?

    The anonymous volume is initialized from the image's content and is more specific than the bind mount over /app, so the installed dependencies show through.
  5. 5. What is the difference between docker compose exec and docker compose run?

    exec attaches to an existing container, run creates a throwaway one (with the service's mounts, network and environment) and also starts dependencies unless --no-deps is used.

Summary

  • A good dev loop avoids rebuilding images for every edit: bind-mount code or let develop.watch sync it.
  • File watchers depend on inotify events, which bind mounts from Windows or macOS hosts may not deliver.
  • docker compose up --watch (or watch) syncs host changes into the container; pair sync with the language's own reloader, and use rebuild for dependency files.
  • Protect installed dependency folders with an anonymous volume when bind-mounting a whole project.
  • exec runs inside a running container; run --rm starts a throwaway container for one-off tasks.
  • Keep dev-only settings out of the production file by using override files.

Next: Multiple Files, Profiles and Extends