Compose Watch

The development loop that puts people off containers is: edit a file, rebuild the image, recreate the container, wait, refresh. Thirty seconds for a one-character change.

The old workaround was bind-mounting your source in, which works until it does not — the dependency directory disappears under the mount, the UIDs are wrong, and a change to package.json needs a rebuild the mount cannot give you.

Compose Watch is the built-in answer, and it distinguishes between changes that need copying and changes that need rebuilding.

The three actions

services:
  web:
    build: .
    command: npm run dev
    ports:
      - "127.0.0.1:3000:3000"
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/

        - action: rebuild
          path: ./package.json

        - action: sync+restart
          path: ./config/app.yaml
          target: /app/config/app.yaml

docker compose up --watch          # run the stack and watch
docker compose watch               # watch only, logs kept separate

sync copies changed files into the running container. Nothing restarts. For anything with hot reload — Vite, nodemon, flask --debug, air — this is the fast path, and it is genuinely instant.

rebuild builds a new image and replaces the container. For a dependency manifest, or a compiled language where the source is not what runs.

sync+restart copies the file and restarts the container's process without rebuilding. For configuration a running process reads once at startup.

Why this beats a bind mount

Watch copies into the container rather than mounting over it. That single difference removes the three classic bind-mount problems:

• Nothing gets hidden. The image's node_modules at /app/node_modules stays exactly where it was, because no mount is covering /app. No anonymous-volume workaround needed.
• Ownership is the container's. Files arrive owned by the container's user, so no permission-denied on a file your host user created.
• Rebuilds are part of the model. A bind mount has no concept of "this change needs a new image". Watch does.

The cost is that it is one-directional: files a container generates do not come back to the host. Anything you need on the host — a generated migration, a lockfile update — still wants a bind mount or a docker compose cp.

ignore, and why it matters more than it looks

        - action: sync
          path: .
          target: /app
          ignore:
            - node_modules/
            - .git/
            - "*.log"
            - dist/

ignore paths are relative to path. Without them, watching a project root means watching every dependency directory and every build artifact — thousands of files, a constant stream of sync events, and on macOS and Windows a noticeable CPU cost from the filesystem event bridge.

Watch also honours .dockerignore for rebuild actions, but ignore is what governs sync. They are worth keeping consistent.

A complete development file

services:
  api:
    build:
      context: .
      target: dev
    command: npm run dev
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://app:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: sync
          path: ./public
          target: /app/public
        - action: rebuild
          path: ./package.json

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      retries: 5

volumes:
  pgdata:

Note target: dev on the build. Watch pairs naturally with a multi-stage Dockerfile that has a dev stage carrying the dev dependencies and the watcher, and a production stage that has neither.

Next up: healthchecks, signals, and lifecycle — making a container start, stop, and fail the way you intended.