Developing with Docker: hot reload, debugging, tests and CI

Hot reloading

Rebuilding an image for every one-line change is too slow for development. Two ways to get changes into a running container:

A bind mount (lesson 6) shares the folder itself:

$ docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD/src":/app/src hello-dev npm run dev

Mount only the source folder, not the whole project: mounting . over /app hides the node_modules the image installed for Linux behind your laptop's own.

Compose watch syncs only the paths you list, and knows when a rebuild is needed instead. A small Node app:

# compose.yaml
services:
  app:
    build: .
    ports:
      - "127.0.0.1:3000:3000"
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

The image runs node --watch src/server.js, Node's built-in reloader. Then:

$ docker compose watch
Watch enabled
$ curl -s localhost:3000
hello v1
$ sed -i 's/hello v1/hello v2, synced/' src/server.js       # or save in your editor
$ curl -s localhost:3000
hello v2, synced
$ docker compose logs app | tail -3
app-1  | listening on 3000
app-1  | Restarting 'src/server.js'
app-1  | listening on 3000

⤢ View

Code is synced in and reloaded by the app; dependency changes rebuild the image.© Animation: DevOps Academy

Close

Compiled languages like Go can use rebuild on the source folder, or a dev image running a watcher such as air.

Debugging

Most problems are found with tools you already know:

$ docker compose logs -f app                 # what did it print?
$ docker compose exec app sh                 # look around inside
$ docker inspect shop-api-1 --format '{{json .State}}'    # exit code, OOMKilled, health log
$ docker compose run --rm app env            # what configuration does it really get?

For a step-through debugger, start the runtime in debug mode, publish the port on loopback only and attach your editor:

    command: ["node", "--inspect=0.0.0.0:9229", "src/server.js"]
    ports:
      - "127.0.0.1:9229:9229"

0.0.0.0 inside the container is needed so the published port reaches it; 127.0.0.1 on the host keeps everyone else out. Python's debugpy and Java's JDWP work the same way. For an image with no shell (lesson 7), attach a tools container to its namespaces: docker run --rm -it --pid container:api --network container:api alpine:3.22 sh.

Tests in containers

Run the tests in the same image you develop and ship with, so a test that passes on your laptop passes in CI:

$ docker compose run --rm --no-deps app npm test
# tests 1
# pass 1
# fail 0

run --rm starts a one-off container from the service's configuration and removes it afterwards; --no-deps skips starting the database when the tests don't need it. For integration tests, let Compose start the dependencies (depends_on with health checks, lesson 9), and run docker compose down -v at the end so every run starts from a clean database.

A multi-stage Dockerfile can include a test stage, so a failing test fails the build:

FROM build AS test
RUN go test ./...

$ docker build --target test .

Docker in CI

CI runners start empty every time, so without help every build starts from zero. The CI/CD course builds a full pipeline; the Docker part looks like this in GitHub Actions:

      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:sha-${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

cache-from and cache-to store BuildKit's layer cache in GitHub's cache service, so the dependency-install layers from lesson 7 are reused between runs. mode=max also caches the build stage's layers, not just the final image's. Other CI systems use a registry cache (type=registry,ref=…:buildcache). Tag with the commit SHA (lesson 8), scan before pushing (lesson 11), and pin actions to a full commit SHA as the CI/CD course's security lesson explains.

$ mkdir -p src test
$ printf "require('node:http').createServer((q, s) => s.end('hello v1\\\\n')).listen(3000, () => console.log('listening on 3000'));\n" > src/server.js
$ printf '{ "name": "hello", "scripts": { "dev": "node --watch src/server.js", "test": "node --test" } }\n' > package.json
$ printf "require('node:test')('adds', () => require('node:assert').strictEqual(1 + 1, 2));\n" > test/server.test.js
$ printf 'FROM node:22-alpine\nWORKDIR /app\nCOPY package.json ./\nRUN npm install --omit=dev\nCOPY . .\nCMD ["npm", "run", "dev"]\n' > Dockerfile
$ # write compose.yaml from this lesson, then in a second terminal:
$ docker compose watch
$ curl -s localhost:3000
hello v1
$ sed -i 's/hello v1/hello v2/' src/server.js && sleep 2 && curl -s localhost:3000
hello v2
$ docker compose run --rm --no-deps app npm test | grep -E '^# (pass|fail)'
# pass 1
# fail 0
$ docker compose down