What is Docker Compose Watch and what problem does it solve?

Table of Contents

Quick Update: Docker Compose File Watch is no longer an experimental feature. I recommend you to either use the latest version of Docker Desktop or use Docker Compose 2.20 or greater to leverage the latest features. Check the recent announcement from Docker Team

Containerization has become an integral part of modern software development, offering numerous benefits such as portability, scalability, and reproducibility. Docker Compose, a popular tool in the Docker ecosystem, simplifies the management of multi-container applications. With the release of Docker Compose v2.17, a new feature called “Docker Compose Watch” has been introduced, aiming to streamline the development workflow and address concerns around slow builds and developer experience. In this blog post, we will explore Docker Compose Watch, understand its functionalities, and see how it solves common challenges in containerized development.

Understanding Docker Compose Watch

Docker Compose Watch is a file watch command that automates the update process for running Docker Compose services as developers edit and save their code. By monitoring specified file or directory paths on the host machine, Docker Compose Watch detects changes and performs corresponding actions within the service container. This capability enables developers to instantly see the impact of their code changes without manually triggering image builds or container restarts.

Docker Compose Watch is a feature of Docker Compose that allows you to automatically update your running Compose services as you edit and save your code. This is useful for development workflows where you want to see the changes you make to your code reflected in your running application immediately.

How does Compose Watch work?

Docker Compose Watch works by monitoring the files in your project directory for changes. When a file is changed, Compose will rebuild the corresponding service container and restart it. This ensures that your running application always has the latest code.

Adding Watch in Docker Compose

Add watch sections to one or more services in compose.yaml.
Launch a Compose project with docker compose up --build --wait.
Run docker compose alpha watch to start the file watch mode.
Edit service source files using your preferred IDE or editor.

The watch section contains two actions:

sync
rebuild

The sync action specifies a path to watch for changes in the host file system, and a corresponding target path inside the container to synchronize changes to.

The rebuild action specifies a path to watch for changes in the host file system, and triggers a rebuild of the container when changes are detected.

What problems does Compose Watch solve? What are its benefits?

The problem that Docker Compose Watch solves is the need to manually restart your services every time you make a change to your code. This can be time-consuming and disruptive, especially if you are making a lot of changes. With Docker Compose Watch, you can make changes to your code and see the results immediately, without having to restart your services.

Benefits and Use Cases

Docker Compose Watch offers several benefits that enhance the developer experience and simplify containerized development:

Rapid Feedback Loop: With Docker Compose Watch, developers receive immediate feedback on code changes. As they save their files, the running Compose services automatically update, eliminating the need for manual rebuilds and restarts. This accelerated feedback loop improves productivity and facilitates iterative development.
Reduced Build Time: By synchronizing only the changed files, Docker Compose Watch optimizes the build process, reducing the time required for image builds. It eliminates the need to rebuild the entire image for every code modification, making the development workflow more efficient.
Seamless Container Updates: Docker Compose Watch ensures that developers always work with the latest code inside the containers. As changes are detected, the relevant files are synced, and containers are recreated when necessary. This seamless update process prevents inconsistencies between development environments and production deployments.

Configuring Docker Compose Watch

To leverage Docker Compose Watch, a new section called develop needs to be added to the Compose YAML file. Within this section, the watch option is available, allowing developers to define the files or directories to monitor and the actions to be taken inside the container.

Let’s take a look at an example:

services:
  web:
    build: .
    develop:
      watch:
        - action: sync
          path: ./web
          target: /src/web
        - action: rebuild
          path: package.json

The develop section in your Docker Compose file allows you to configure watch options for your services. In this case, you are configuring two watch options:

The first watch option will watch the api/requirements.txt file and rebuild the service container if the file is changed.
The second watch option will watch the api/ directory and sync the changes to the /app/api/ directory in the container.
The action property of the watch option specifies what to do when the file is changed.

In the first case, the rebuild action will rebuild the service container. In the second case, the sync action will sync the changes to the /app/api/ directory in the container.

The target property of the watch option specifies the directory in the container where the changes should be synced. In this case, the target property is set to /app/api/, so the changes to the api/ directory will be synced to the /app/api/ directory in the container.

In the above example, the web service is configured to sync changes made in the ./web directory with the corresponding location /src/web inside the container using the sync action. This synchronization is especially useful when combined with frameworks supporting hot module reload. Additionally, changes to the package.json file trigger a rebuild of the image and recreation of the service container using the rebuild action.

Sample Application: Avatars

To demonstrate the capabilities of Docker Compose Watch, let’s consider a sample application called “Avatars.” The source code for this application is available at https://github.com/dockersamples/avatars.git. Follow these steps to run the application and experience Docker Compose Watch in action:

Clone the repository:

git clone https://github.com/dockersamples/avatars.git
cd avatars

Examining the Compose file

services:
  api:
    image: avatars-api
    build:
      context: .
      dockerfile: ./deploy/api.dockerfile
    ports:
      - 5734:80
    develop:
      watch:
        - path: api/requirements.txt
          action: rebuild
        - path: api/
          target: /app/api/
          action: sync

  web:
    image: avatars-web
    build:
      context: .
      dockerfile: ./deploy/web.dockerfile
    ports:
      - 5735:5173
    develop:
      watch:
        - path: web/package.json
          action: rebuild
        - path: web/yarn.lock
          action: rebuild
        - path: web/
          target: /app
          action: sync

The services section in your Docker Compose file defines the services that will be created. In this case, you are defining two services: api and web.

The api service will be built from the api.dockerfile file in the deploy directory. The api service will listen on port 5734. The develop section for the api service defines two watch options:

The first watch option will watch the api/requirements.txt file and rebuild the service container if the file is changed.
The second watch option will watch the api/ directory and sync the changes to the /app/api/ directory in the container.
The web service will be built from the web.dockerfile file in the deploy directory. The web service will listen on port 5735. The develop section for the web service defines three watch options:
The first watch option will watch the web/package.json file and rebuild the service container if the file is changed.
The second watch option will watch the web/yarn.lock file and rebuild the service container if the file is changed.
The third watch option will watch the web/ directory and sync the changes to the /app directory in the container.

Start the application:

docker compose up -d

Accessing the Application

Open your browser and access the app via https://localhost:5735

Enable Docker Compose Watch

docker compose watch

As you make changes to the Avatars application code, Docker Compose Watch will automatically sync the modified files and reflect the changes in the running containers, allowing you to observe the immediate impact of your code modifications.

Compose Watch Rebuild

Go to requirements.txt file under api/ directory and add a new package such as Django, for example.

docker compose watch
watching [/Users/ajeetsraina/july/avatars/api/requirements.txt /Users/ajeetsraina/july/avatars/api]
watching [/Users/ajeetsraina/july/avatars/web/package.json /Users/ajeetsraina/july/avatars/web/yarn.lock /Users/ajeetsraina/july/avatars/web]
change detected on /Users/ajeetsraina/july/avatars/api/requirements.txt
change detected on /Users/ajeetsraina/july/avatars/api/requirements.txt
Rebuilding api after changes were detected:
  - /Users/ajeetsraina/july/avatars/api/requirements.txt
[+] Building 3.3s (22/22) FINISHED
 => [api internal] load build definition from api.dockerfile                                                                                               0.0s
 => => transferring dockerfile: 403B                                                                                                                       0.0s
 => [api internal] load .dockerignore                                                                                                                      0.0s
 => => transferring context: 95B                                                                                                                           0.0s
 => [api internal] load metadata for docker.io/library/python:3.10-slim-bullseye                                                                           3.2s
 => [web internal] load .dockerignore                                                                                                                      
 => [web] exporting to image                                                                                                                               
 => CACHED [api stage-0 5/5] COPY api/ ./api/                                                                                                              
 => => naming to docker.io/library/avatars-api:latest                                                                                                      0.0s
 => => unpacking to docker.io/library/avatars-api:latest                                                                                                   0.0s
[+] Running 2/2
 ✔ Container avatars-web-1  Started                                                                                                                        0.6s
 ✔ Container avatars-api-1  Started

Compose Watch Sync

Try replacing the docker_tshirt.svg file with your favourite color, then you will see sync updates in the docker compose watch window.

To watch a specific file

Here are some more examples of how you can use Compose watch:

services:
  web:
    build: .
    command: 'npm start'
    # Enable compose watch
    develop:
      watch:
        - ./src/index.js

In this example, Compose will only watch the index.js file in the src directory.

To watch a directory and all of its subdirectories:

services:
  web:
    build: .
    command: 'npm start'
    # Enable compose watch
    develop:
      watch:
        - ./src/**/*

In this example, Compose will watch all files in the src directory and all of its subdirectories.

To watch a file and ignore changes to other files

services:
  web:
    build: .
    command: 'npm start'
    # Enable compose watch
    develop:
      watch:
        - ./src/index.js
        # Ignore changes to other files
        - !./src/other.js

In this example, Compose will only watch the index.js file in the src directory. Any changes to other files will be ignored.

Conclusion

Docker Compose Watch is a valuable addition to the Docker Compose ecosystem, empowering developers with an efficient and streamlined containerized development workflow. By automating the update process for running services, Docker Compose Watch reduces build times, provides rapid feedback on code changes, and ensures that developers work with the latest code inside the containers.

Docker Compose Watch demonstrates the commitment of Docker Compose to improve the developer experience and addresses the challenges associated with local container development. As developers embrace containerization for their daily workflow, Docker Compose Watch proves to be an indispensable tool for enhancing productivity and maintaining development environments that are in sync with production deployments.

🐳 Boost Your Docker Workflow: Introducing Docker Init for Python Developers 🚀

Introducing Docker Init: Generating Docker Assets for Your Projects