Day 6: Developing with compose watch
Goal: Change code, save, see the result – without running
docker compose up --buildby hand, with a dev target for web. · Duration: approx. 60 min · Prerequisite: Day 5
Briefing
develop.watchdescribes 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 watchstarts the stack and watches the paths;docker compose up --watchdoes the same and additionally shows the logs..dockerignorealso applies while watching: whatever must not go into the image is not synced either.- Compose automatically loads a
compose.override.yamlnext tocompose.yaml. In it, web runs in the build stage withnode --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-workerIn a second terminal (same folder), start the watcher and leave it open:
cd ~/compose-lab/tag06 && docker compose watchExpected (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 -2Expected (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__.pySave 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/srcwatch 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/publicExpected (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.htmlSave 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=notesExpected (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.txtExpected:
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 -2Expected (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.jsSave 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.mdExpected:
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 %1Expected:
<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 %1Expected:
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.yamlExpected (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' ' '; echoExpected:
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.txtExpected:
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.txtExpected:
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 %1Expected (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/finaltarget in CI. - Bind mounts of the whole source folder are the older alternative to
sync; on macOS they are slower, andnode_modulesfrom 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. .dockerignoreis also a security boundary for watch: keys,.envand certificates must get neither into the image nor into a container via sync.