A Glimpse into Docker Compose Watch

It’s a good time to be a Docker Compose user — a couple weeks ago, Compose v2.22 dropped, and among its new features is the highly-anticipated Watch mode.

What is Docker Compose Watch?

Docker Compose Watch is a mode for running your Compose app that automatically updates your containers based on any changes you make to your watched files and directories.

Containers don’t support hot reload by default. When you’re iterating on a project and want to see your code changes, you’ll need to rebuild and restart your services. Compose Watch makes container-based development more responsive: by designating certain filepaths as “watched”, Compose will monitor and sync or rebuild the updated file(s) within your running container. This way, you can focus on developing and previewing without CTRL C’ing your Compose processes every few minutes.

Compose Watch is best used for services that support dynamic reloading. This is especially helpful for things like JavaScript that typically require a restart when running within a container.

Using Docker Compose Watch

Compose’s Watch mode is accessed via the CLI: run docker compose watch in your project’s root directory to trigger it. But wait: before you can expect your services to update, you’ll need to update your project’s Compose file.

For services that you’re actively updating, you can now add a develop section (Docker’s develop section currently only supports watch). Within this section, you can configure your Watch settings.

web:
  build: .
  ports:
    - 3000:3000
  develop:
    watch:
      - action: sync
        path: ./web
        target: /src/web

Compose Watch supports two different actions upon file changes: sync and rebuild.

• sync is used to update a file/directory within the running container
• rebuild is used to rebuild and replace the running container

Note: Compose Watch should only be used during development.

Compose Watch Example: React + Flask App

I wanted to try this out on my own to see Watch in action. I used an existing repo, Shipyard’s React + Flask Starter, and made a few changes to the Compose file’s frontend service. Here’s what the service looked like initially:

frontend:
  labels:
    shipyard.route: '/'
  build: ‘frontend’
  env_file:
    - frontend/frontend.env
  volumes:
    - './frontend/src:/app/src'
    - './frontend/public:/app/public'
  ports:
    - '3000:3000'

Enabling Watch on this service took all of 30 seconds. I just remapped the mounts to watch points that will use the sync action when edited. I set path to the local filepath, and target to the corresponding path within the container.

frontend:
 labels:
   shipyard.route: '/'
 build: 'frontend'
 env_file:
   - frontend/frontend.env
 develop:
   watch:
     - action: sync
       path: ./frontend/src
       target: /app/src
     - action: sync
       path: ./frontend/public
       target: /app/public
 ports:
   - '3000:3000'

I ran the docker compose watch command and then edited a JavaScript file from one of the watched directories. Within seconds, Compose detected a change and synced the newly-edited file:

watching [./frontend/src ./frontend/public]
Syncing frontend after changes were detected:
- ./frontend/src/components/MaterialCard.js

My new JavaScript function executed as soon as I visited my localhost, no rebuilds required.

If you want to try this out on the React + Flask Starter, here’s a Gist with the Watch-enabled Compose service.

Check it out now

You can start using Docker Compose Watch as soon as you install Compose v2.22. As of today, it’s available when you update Docker Desktop. Read the Compose docs for more info on how Watch mode works, and check out this Docker sample project to see it for yourself.

Enjoy the faster inner dev loop!