Update automatically Docker containers with Watchtower on Ubuntu

Using Docker provides many benefits like allowing you to package applications into standardized units for software development. This makes it easier to deploy and scale your applications.

However, managing updates of the Docker images on a server can become tedious. You have to manually pull new versions of an image and restart each container every time an update is released.

This is where Watchtower comes in handy! Watchtower is a container-based solution that will monitor your running Docker containers and watch for changes to the images that those containers were originally started from.

When Watchtower detects that an image has changed, it will automatically restart the related containers to pull down the new image and run with the latest version.

In this comprehensive guide, we will cover how to install Watchtower and configure it to automatically update containers on Ubuntu 20.04/22.04.

Prerequisites

Before we get started with setting up Watchtower, there are a few prerequisites you need:

• A Ubuntu 20.04/22.04 server with Docker installed
• You can follow the Docker installation guide for Ubuntu 20.04/22.04
• Docker configured to auto-start on boot (should be default)
• A few Docker containers already running on the server that you wish to keep updated

Once you have your Ubuntu server ready with Docker active and some containers running, we can move on to installing Watchtower.

Step 1 – Install Watchtower

Watchtower is distributed as a Docker image, so installation is as simple as running a container from that image. The Watchtower image is hosted on Docker Hub.

Pull down the latest Watchtower image:

$ docker pull containrrr/watchtower

Once the image finishes downloading, you can run a Watchtower container:

$ docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower

Let’s go over the options we are passing to the docker run command:

• -d – Runs the Watchtower container in detached mode
• --name watchtower – Names the container “watchtower” for easier identification
• -v /var/run/docker.sock:/var/run/docker.sock – Mounts the Docker socket into the Watchtower container so it can communicate with the Docker daemon
• containrrr/watchtower – The Watchtower Docker image to use

This will create and start up a Watchtower container in the background that is ready to start monitoring your other containers.

Step 2 – Configure Watchtower Notification Options

By default, Watchtower will silently check for container image updates in the background without notifying you. You can change this behavior by setting a few environment variables when launching Watchtower:

Notifications on Containers Updated

To get notifications when Watchtower updates containers, pass in the -e WATCHTOWER_NOTIFICATIONS=email environment variable.

There are a few options for notifications:

• email – Will send email notifications. Requires additional configuration.
• slack – Can post notifications to Slack. Requires webhook URL and channel.
• msteams – Send notifications to MS Teams. Requires webhook URL.
• gotify – Send notifications through Gotify. Requires app token and server URL.

For example:

$ docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock -e WATCHTOWER_NOTIFICATIONS=email containrrr/watchtower

This will enable email notifications when containers are updated.

Notifications on Watchtower Start/Exit

You can also get notifications when the Watchtower container starts up or shuts down by passing in -e WATCHTOWER_NOTIFICATIONS_LEVEL=start-exit:

$ docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock -e WATCHTOWER_NOTIFICATIONS=email -e WATCHTOWER_NOTIFICATIONS_LEVEL=start-exit containrrr/watchtower

This will send notifications on both container updates and when Watchtower starts/stops.

Notification Services Configuration

If you enable notifications, you will need to provide configuration for the notification services.

This is done by passing in additional environment variables or by mounting YAML configuration files into the container.

Email Configuration

To receive email notifications, you must provide:

• WATCHTOWER_EMAIL_FROM – The address to send notification emails from
• WATCHTOWER_EMAIL_TO – The address to send notifications to
• WATCHTOWER_EMAIL_SERVER – SMTP server address
• WATCHTOWER_EMAIL_SERVER_PORT – SMTP server port
• WATCHTOWER_EMAIL_SERVER_USER – SMTP user name
• WATCHTOWER_EMAIL_SERVER_PASSWORD – SMTP password

For Gmail, it would look something like:

$ docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=email \
  -e [email protected] \ 
  -e [email protected] \
  -e WATCHTOWER_EMAIL_SERVER=smtp.gmail.com \
  -e WATCHTOWER_EMAIL_SERVER_PORT=587 \
  -e [email protected] \
  -e WATCHTOWER_EMAIL_SERVER_PASSWORD=gmail_password \
  containrrr/watchtower 

Slack Configuration

To post to Slack, you need:

• WATCHTOWER_NOTIFICATIONS_SLACK_WEBHOOK_URL – Your Slack webhook URL
• WATCHTOWER_NOTIFICATIONS_SLACK_CHANNEL – The Slack channel to post to

For example:

$ docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=slack \
  -e WATCHTOWER_NOTIFICATIONS_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx \
  -e WATCHTOWER_NOTIFICATIONS_SLACK_CHANNEL="#channel-name" \
  containrrr/watchtower

MS Teams Configuration

For MS Teams notifications, you only need to provide:

• WATCHTOWER_NOTIFICATIONS_MSTEAMS_WEBHOOK_URL – Your MS Teams webhook URL

For example:

$ docker run -d --name watchtower -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=msteams \
  -e WATCHTOWER_NOTIFICATIONS_MSTEAMS_WEBHOOK_URL=https://webhook.teams.microsoft.com/xxx \
  containrrr/watchtower

Using Configuration Files

Instead of passing environment variables, you can define your notification configurations in YAML files and mount them into the Watchtower container.

This allows you to keep your configurations externally and not have to pass long command strings.

The configuration file paths:

• /config/email.yaml – Email configuration
• /config/slack.yaml – Slack configuration
• /config/msteams.yaml – MS Teams configuration

Just mount your custom YAML files over top of the default empty files.

For example for email notifications:

$ docker run -d --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/email.yaml:/config/email.yaml \
  containrrr/watchtower

Where your email.yaml would contain:

email:
  from: [email protected]
  to: [email protected]
  server: smtp.gmail.com
  port: 587
  user: [email protected]
  password: gmail_password

This keeps your notification configurations external and detachable from the Watchtower container itself.

Step 3 – Control Which Containers Are Updated

By default, Watchtower will monitor all containers running on the Docker daemon and update any containers where the image is refreshed.

You can exclude containers by name or label to prevent Watchtower from updating them automatically:

Exclude by Container Name

Pass the --exclude option with a regex filter for names:

$ docker run -d --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --exclude "my-container-name|another-container"

Exclude by Container Label

Label containers with com.centurylinklabs.watchtower.enable=false to exclude:

$ docker run -d --label com.centurylinklabs.watchtower.enable=false nginx

Containers with that label will be ignored by Watchtower.

Include Only Matching Containers

You can also whitelist containers to only update containers matching a pattern by using --include:

$ docker run -d --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --include "container-a|container-b" 

Now Watchtower will only automatically update containers named container-a or container-b, ignoring all others.

Step 4 – Change the Watchtower Polling Intervals

Watchtower will check for new images every few minutes by default. You can change how frequently Watchtower polls for new images.

Check for New Images

To change how often Watchtower checks for new images, pass the --interval option with a duration string:

$ docker run -d --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower --interval 5m

This will make Watchtower check for new images every 5 minutes.

Restart Containers

By default, Watchtower will wait 10 minutes after an image update before restarting containers. You can modify the duration Watchtower waits before restarting with --restart-delay:

$ docker run -d --name watchtower \
 -v /var/run/docker.sock:/var/run/docker.sock \
 containrrr/watchtower --restart-delay 2m

This will set the restart delay to 2 minutes.

Step 5 – Automate Watchtower Startup

The last step is to make sure Watchtower is automatically started when the Docker daemon starts up. This will run Watchtower each time you reboot the server.

You can create a simple systemd unit file to start Watchtower on boot.

Create a unit file at /etc/systemd/system/watchtower.service with this definition:

[Unit]
Description=Watchtower - Auto update Docker containers
Requires=docker.service
After=docker.service
[Service]
Restart=always
ExecStart=/usr/bin/docker start -a watchtower
ExecStop=/usr/bin/docker stop -t 2 watchtower
[Install]
WantedBy=multi-user.target

This will start the Watchtower container we created when the Docker daemon starts up.

Reload systemd and enable the Watchtower service to start on boot:

$ sudo systemctl daemon-reload
$ sudo systemctl enable watchtower

Watchtower will now automatically run each time you restart the server.

Step 6 – Set Up Watchtower in Docker Compose

You can also run Watchtower as part of a Docker Compose stack.

Add a watchtower service to your docker-compose.yml file like this:

version: "3"
services:
  app:
    image: myapp
    ports:
      - "8080:80"
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 30

This will start Watchtower along with the app/service containers defined in your compose file.

Watchtower will monitor the other services and automatically update any images as new versions are released.

The volumes mount the Docker socket so Watchtower can communicate with the Docker daemon.

The command sets the check interval to 30 seconds. You can customize this interval as needed.

Now when you run docker-compose up, Watchtower will keep your images updated out of the box!

Using Docker Compose allows you to easily add Watchtower monitoring to new and existing stacks. Just add the watchtower service and volume mount to begin auto-updating any new or existing images.

Conclusion

In this guide we covered how to install and configure Watchtower to automatically update your Docker containers.

Key takeaways include:

• Watchtower runs as a Docker container to monitor other containers
• Notifications can alert you when Watchtower updates containers
• Exclude containers from auto-updates by name or label
• Change the frequency Watchtower checks for new images
• Create a systemd unit file to launch Watchtower on boot

With Watchtower running, you no longer have to manually check for Docker image updates or restart containers. Watchtower will keep your containers running the latest versions automatically in the background.

This makes managing container updates much easier as your stack grows in size. Give Watchtower a try to simplify keeping your containers current!