Skip to content
Hands-on IT IT Drills

Day 6: Developing with compose watch

Goal: Change code, save, see the result – without running docker compose up --build by hand, with a dev target for web. · Duration: approx. 60 min · Prerequisite: Day 5

Briefing

  • develop.watch describes per service what happens when a file changes: rebuild (rebuild the image, replace the container), sync (copy the file into the running container), sync+restart (copy, then restart the container).
  • docker compose watch starts the stack and watches the paths; docker compose up --watch does the same and additionally shows the logs.
  • .dockerignore also applies while watching: whatever must not go into the image is not synced either.
  • Compose automatically loads a compose.override.yaml next to compose.yaml. In it, web runs in the build stage with node --watch.
 notes-api/**        ──rebuild──────► api     (new image, new container)
 notes-worker/**     ──rebuild──────► worker
 notes-web/public/   ──sync─────────► web:/app/public
 notes-web/server.js ──sync+restart─► web:/app/server.js
 notes-web/src/, package.json ──rebuild──► web

Drill 1: rebuild for api and worker

source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag06 && cd ~/compose-lab/tag06
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag05/notes/." .

Add a develop block to both api and worker (at the end of the service):

  api:
    # … as on Day 5 …
    develop:
      watch:
        - action: rebuild
          path: ./notes-api

  worker:
    # … as on Day 5 …
    develop:
      watch:
        - action: rebuild
          path: ./notes-worker

In a second terminal (same folder), start the watcher and leave it open:

cd ~/compose-lab/tag06 && docker compose watch

Expected (shortened, build output omitted):

 Image notes-api Built
 Image notes-worker Built
 Image notes-web Built
 Container notes-db-1 Healthy
 Container notes-migrate-1 Exited
 Container notes-api-1 Healthy
 Container notes-web-1 Started
Watch enabled

Back in the first terminal: a change to notes-api.

curl -s localhost:8080/healthz
sed -i '' 's#fmt.Fprintln(w, "ok")#fmt.Fprintln(w, "ok (Tag 6)")#' notes-api/main.go
sleep 10
curl -s localhost:8080/healthz
docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'

On Linux it’s sed -i without ''. Expected (shortened, times differ on your machine):

ok
ok (Tag 6)
SERVICE   STATUS
api       Up 2 seconds (healthy)
db        Up 2 minutes (healthy)
migrate   Exited (0) 1 second ago
web       Up 11 seconds (healthy)
worker    Up 2 minutes

In the second terminal:

Rebuilding service(s) ["api"] after changes were detected...
service(s) ["api"] successfully built
 Container notes-api-1 Recreate
 Container notes-api-1 Recreated
 Container notes-api-1 Started

After about three seconds the new container was running – the Go build came almost entirely from the cache. migrate ran again along the way, because api depends on it (Day 5). The same for worker:

sed -i '' 's#print(f"summary: #print(f"Zusammenfassung: #' \
  notes-worker/src/notes_worker/__init__.py
sleep 12
docker compose logs worker | tail -2

Expected (shortened):

worker-1  | worker started, api=http://api:8080, interval=10s
worker-1  | Zusammenfassung: 0 notes, 0 words

Revert (watch rebuilds again in the process):

sed -i '' 's#"ok (Tag 6)"#"ok"#' notes-api/main.go
sed -i '' 's#print(f"Zusammenfassung: #print(f"summary: #' \
  notes-worker/src/notes_worker/__init__.py

Save your progress? Sign up for free

Drill 2: sync into the prod image

Now web. Add to web:

  web:
    # … as on Day 5 …
    develop:
      watch:
        - action: sync
          path: ./notes-web/public
          target: /app/public
        - action: sync+restart
          path: ./notes-web/server.js
          target: /app/server.js
        - action: rebuild
          path: ./notes-web/package.json
        - action: rebuild
          path: ./notes-web/src

watch reads the file only at startup: in the second terminal press Ctrl+C, then run docker compose watch again. web is still running with the prod image from Day 5 – as user node; /app belongs to root:

docker compose exec web sh -c 'id; ls -ld /app/public /app/public/index.html'
sed -i '' 's#<h1>notes</h1>#<h1>notes (watch)</h1>#' notes-web/public/index.html
sleep 5
curl -s localhost:3000/ | grep '<h1>'
echo "hallo aus watch" > notes-web/public/hallo.txt
sleep 5
docker compose exec web ls -ln /app/public
rm notes-web/public/hallo.txt
sleep 5
docker compose exec web ls /app/public

Expected (shortened):

uid=1000(node) gid=1000(node) groups=1000(node)
drwxr-xr-x    2 root     root          4096 Oct 29 20:23 /app/public
-rwxr-xr-x    1 root     root           273 Oct 29 20:23 /app/public/index.html
  <h1>notes (watch)</h1>
-rw-r--r--    1 1000     1000            16 Oct 29 20:48 hallo.txt
-rwxr-xr-x    1 1000     1000           283 Oct 29 20:48 index.html
hallo.txt
index.html

In the second terminal:

Syncing service "web" after 1 changes were detected
rm: can't remove '/app/public/hallo.txt': Permission denied
… level=warning msg="Error handling changed files: deleting paths in …: exit code 1"

Half-working is the most dangerous variant: new and changed files arrive (Compose copies them via the Docker API and hands them over to UID 1000), but Compose performs deletion with rm as the container user – and node isn’t allowed to delete anything in root’s folder. That’s why the docs require the USER to be able to write to the target. Restore index.html:

sed -i '' 's#<h1>notes (watch)</h1>#<h1>notes</h1>#' notes-web/public/index.html

Save your progress? Sign up for free

Drill 3: Dev target via compose.override.yaml

Instead of softening the prod image, web runs in the Dockerfile’s build stage during development: root, all dev dependencies, source code in /app.

cat > compose.override.yaml <<'EOF'
# compose.override.yaml – development (Day 6), loaded automatically
services:
  web:
    build:
      target: build
    command: ["node", "--watch", "server.js"]
    environment:
      NODE_ENV: development
EOF
docker compose config --format json \
  | jq -c '.services.web | {target: .build.target, command, env: .environment.NODE_ENV}'
docker compose ls --filter name=notes

Expected (paths differ):

{"target":"build","command":["node","--watch","server.js"],"env":"development"}
NAME                STATUS              CONFIG FILES
notes               running(4)          /Users/du/compose-lab/tag06/compose.yaml,/User…

Compose merges both files; the details of the rules come on Day 7. In the second terminal press Ctrl+C. First start without a build:

docker compose up -d --wait >/dev/null 2>&1
docker compose exec web id -un
docker compose up -d --wait --build >/dev/null 2>&1
docker compose exec web sh -c 'id -un; ls /app; cat /proc/1/cmdline | tr "\0" " "'
echo
docker image ls --filter reference=notes-web --format '{{.Repository}} {{.Size}}'

Expected (shortened):

node
root
dist
node_modules
package-lock.json
package.json
public
server.js
src
node --watch server.js
notes-web 280MB

The trap in the first line: without --build, Compose only builds if the image is missing. web ran with the new command, but in the old prod image. Note also: the dev image is also called notes-web and replaces the prod image – separate tags come on Day 8. Restart docker compose watch in the second terminal; it builds by itself at startup.

Save your progress? Sign up for free

Drill 4: sync, sync+restart, rebuild

echo "hallo aus watch" > notes-web/public/hallo.txt
sleep 4; curl -s localhost:3000/hallo.txt
rm notes-web/public/hallo.txt
sleep 4; curl -s -o /dev/null -w 'hallo.txt nach rm: %{http_code}\n' \
  localhost:3000/hallo.txt

Expected:

hallo aus watch
hallo.txt nach rm: 404

As root, deleting works too. Now server.js (action sync+restart):

docker inspect -f '{{.State.StartedAt}}' notes-web-1
sed -i '' 's#notes-web listening on#notes-web (dev) listening on#' notes-web/server.js
sleep 8
docker inspect -f '{{.State.StartedAt}}' notes-web-1
docker compose logs web | tail -2

Expected (shortened, times differ):

2026-10-29T20:49:10.28…Z
2026-10-29T20:49:46.49…Z
web-1  | SIGTERM received, shutting down
web-1  | notes-web (dev) listening on :3000

The container was restarted. With node --watch, a plain sync would be enough – verified live: Node reports Restarting 'server.js' and restarts only the process; the container keeps running. sync+restart, on the other hand, works with any program. Finally src/: esbuild bundles the code into dist/ during the build, hence rebuild:

sed -i '' 's#^load();$#console.log("notes-web Tag 6");\nload();#' notes-web/src/app.js
sleep 8
curl -s localhost:3000/assets/app.js | grep -o 'notes-web Tag 6'

Expected:

notes-web Tag 6

Revert:

sed -i '' 's#notes-web (dev) listening on#notes-web listening on#' notes-web/server.js
sed -i '' '/^console.log("notes-web Tag 6");$/d' notes-web/src/app.js

Save your progress? Sign up for free

Drill 5: .dockerignore and ignore

echo "GEHEIM=lab-api-key-123" > notes-web/public/.env.local
echo "# Notiz" > notes-web/public/NOTIZ.md
sleep 5
docker compose exec web ls -A /app/public
grep -E '^\*\*/\.env\*|^\*\.md' notes-web/.dockerignore
rm notes-web/public/.env.local notes-web/public/NOTIZ.md

Expected:

NOTIZ.md
index.html
*.md
**/.env*

.env.local matches **/.env* and stays out – good. NOTIZ.md was synced: *.md only applies at the root of the build context (notes-web/); for all levels you need **/*.md (as in the first book). Additional patterns just for watch are set with ignore: in the rule, e.g. ignore: [node_modules/]; paths there are relative to path.

Save your progress? Sign up for free

Drill 6: initial_sync

What happens to changes made while watch isn’t running? In the second terminal press Ctrl+C.

sed -i '' 's#<h1>notes</h1>#<h1>notes (offline geändert)</h1>#' \
  notes-web/public/index.html
docker compose watch --no-up >/dev/null 2>&1 &
sleep 8; curl -s localhost:3000/ | grep '<h1>'; kill %1

Expected:

  <h1>notes</h1>

The container has the old file. Temporarily add the line initial_sync: true to the sync rule for public and repeat the block (the page still says “offline geändert”, i.e. “changed offline”):

docker compose config -q; echo "Exit: $?"
docker compose watch --no-up >/dev/null 2>&1 &
sleep 8; curl -s localhost:3000/ | grep '<h1>'; kill %1

Expected:

Exit: 0
  <h1>notes (offline geändert)</h1>

With initial_sync, Compose reconciles what is under path at startup. Remove the line again and restore index.html (<h1>notes</h1>).

Save your progress? Sign up for free

Drill 7: watch or up --watch

docker compose watch --help | grep -E -- '--no-up|--prune'

Expected:

      --no-up     Do not build & start services before watching
      --prune     Prune dangling images on rebuild (default true)

In the second terminal, start docker compose up --watch, wait for “Watch enabled” and quit with Ctrl+C. Then do the same with docker compose watch. In the first terminal, each time:

docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'

Expected after up --watch and Ctrl+C (shortened):

 Compose Stopping Gracefully Stopping... press Ctrl+C again to force
 Container notes-web-1 Stopped
 Container notes-api-1 Stopped
 Container notes-db-1 Stopped
SERVICE   STATUS
api       Exited (0) Less than a second ago
db        Exited (0) Less than a second ago
…

Expected after watch and Ctrl+C:

SERVICE   STATUS
api       Up 10 seconds (healthy)
db        Up 12 seconds (healthy)
migrate   Exited (0) 11 seconds ago
web       Up 9 seconds (healthy)
worker    Up 9 seconds

up --watch behaves like up in the foreground: logs of all services, Ctrl+C stops the stack. watch shows only its own messages; the stack keeps running after Ctrl+C. --prune removes the old, nameless images after a rebuild.

Save your progress? Sign up for free

Checkpoint

cd ~/compose-lab/tag06
docker compose up -d --build --wait
ls compose.override.yaml

Expected (shortened):

…
 Container notes-db-1 Healthy
 Container notes-api-1 Healthy
 Container notes-web-1 Healthy
 Container notes-worker-1 Healthy
compose.override.yaml

Six watch rules:

docker compose config --format json | jq '[.services[].develop.watch[]?] | length'

Expected:

6

web runs in the build stage as root and with node --watch:

docker compose exec web id -u
docker compose exec web cat /proc/1/cmdline | tr '\0' ' '; echo

Expected:

0
node --watch server.js

Now start watch in a second terminal: docker compose watch --no-up. Then create a file here:

echo kontrollpunkt > notes-web/public/kp.txt
sleep 5
curl -s localhost:3000/kp.txt

Expected:

kontrollpunkt

And delete it again:

rm notes-web/public/kp.txt
sleep 5
curl -s -o /dev/null -w '%{http_code}\n' localhost:3000/kp.txt

Expected:

404

You stop watch in the second terminal with Ctrl+C. You’ll find the complete state in code/tag06/notes/.

Challenge

Make web’s prod image watch-ready enough that deleting also works for public/ – without the dev target. Test it with the override switched off and restore everything afterwards.

Hint: The watch docs recommend COPY --chown; Compose only loads compose.override.yaml as long as it has that name.

Solution

Change one line in the prod stage of notes-web/Dockerfile (solution in code/tag06/challenge/notes-web/Dockerfile):

COPY --chown=node:node public/ ./public/
cd ~/compose-lab/tag06
cp notes-web/Dockerfile /tmp/Dockerfile.orig
cp "$LAB/code/tag06/challenge/notes-web/Dockerfile" notes-web/Dockerfile
docker build --check notes-web 2>&1 | tail -1
mv compose.override.yaml compose.override.yaml.aus
docker compose up -d --wait --build web >/dev/null 2>&1
docker compose exec web sh -c 'id -un; ls -ld /app/public'
docker compose watch --no-up >/dev/null 2>&1 &
sleep 4
echo "hallo" > notes-web/public/hallo.txt
sleep 4; curl -s localhost:3000/hallo.txt
rm notes-web/public/hallo.txt
sleep 4; curl -s -o /dev/null -w 'nach rm: %{http_code}\n' localhost:3000/hallo.txt
kill %1

Expected (shortened):

Check complete, no warnings found.
node
drwxr-xr-x    2 node     node          4096 Oct 29 20:52 /app/public
hallo
nach rm: 404

With --chown, the folder belongs to node, so watch may delete as well. For production that’s a step backwards: an attacker inside the container could modify the pages being served. That’s why the prod image stays unchanged in this book and development runs in the dev target. Revert:

mv compose.override.yaml.aus compose.override.yaml
cp /tmp/Dockerfile.orig notes-web/Dockerfile
docker compose up -d --build --wait >/dev/null 2>&1; echo "Exit: $?"

Expected:

Exit: 0

To finish the day: docker compose down.

Save your progress? Sign up for free

Enterprise Note

  • Dev containers never belong in a registry for production. Separate image names or tags (Day 8) and build only the prod/final target in CI.
  • Bind mounts of the whole source folder are the older alternative to sync; on macOS they are slower, and node_modules from the Mac doesn’t match Linux binaries.
  • Teams with many services start locally only the part they are working on (docker compose watch api), the rest as finished images – or via profiles (Day 7).
  • Remote development environments (Dev Containers, Codespaces, Gitpod) use the same Compose file; they partly ignore develop – check beforehand.
  • .dockerignore is also a security boundary for watch: keys, .env and certificates must get neither into the image nor into a container via sync.