---
tags:
  - Docker
  - Patching
---


<iframe allowfullscreen="allowfullscreen" height="336" src="https://www.youtube.com/embed/1YMqkNv8HKQ" width="600"></iframe>

Watchtower has been on my list for a long time. I’ve avoided it because I was initially told it would just update all of my Docker containers automatically. I’m not one to do auto-update things. I like to read about it, understand the changes, and know if it's going to break anything before I update in 99% of the cases. Now, knowing that, I have rarely had breaking changes in containers, but it definitely does happen.

If you are someone who isn't averse to breaking changes, then you should consider letting Watchtower do it's thing full speed ahead. However, if you are like me, then you'll be happy to know that you can setup Watchtower to simply notify you when there are new versions of your docker images available, and you can then choose to update, or stay where you are.

## Pre-installation Setup

Watchtower Documentation: [https://containrrr.dev/watchtower/notifications/](https://containrrr.dev/watchtower/notifications/)

Before you run Watchtower, you need to decide a couple of things.

1. Do you want Watchtower to update your Containers automatically, or do you want to be notified of available updates only, or do you want Watchtower to completely ignore certain containers?
2. Do you want to set the schedule on which Watchtower runs?
3. How do you want to be notified?

For our setup today, we'll discuss all three options for update automatically, notify only, and ignore. We'll setup notifications via e-mail, and we'll set a schedule using the 6 position cron syntax. There are all things you need to have ready and prepared before running your Watchtower container, or you'll just have all of your containers updated automatically, and pretty much immediately.

### Update Options

If you want to update your containers automatically, you really only need the e-mail SMTP information (or notification setup info for your desired notification method), and if you want it, a schedule cron flag.

If, however, you want to be notified of available updated, but don't want the container to be auto-updated; or you simply want watchtower to ignore certain containers completely, you first need to re-create your containers with a new label.

I do this via Portainer (it's quite easy, and useful to use the Portainer GUI for this, but not necessary if you prefer the CLI). In Portainer, click on the container you want to set the label for, then click the 'Duplicate/Edit' button inside the container space in Portainer.

Now, scroll to the bottom, and click the 'Labels' tab. Add a new label for your preferred action:

#### Notify Only

Add the following as the label `com.centurylinklabs.watchtower.monitor-only` and then enter `true` as the value.

Now click the "Deploy the container" button, and confirm that you want to replace the existing container. This should bring up your container just as it was, and simply add a label to it that Watchtower will read, and know to only notify you if a new version of the image / container is available.

#### Ignore Container

Add the following as the label `com.centurylinklabs.watchtower.enable` and for the value enter `false`.

Now click the "Deploy the container" button, and confirm that you want to replace the existing container. This should bring up your container just as it was, and simply add a label to it that Watchtower will read, and know to ignore the container.

> It is EXTREMELY IMPORTANT that you setup the labels before running Watchtower if you don't want it to update all of your containers immediately.

### SMTP Setup

Next, in order to get notifications (whether in Notify Only, or for containers that have been updated), we'll setup our e-mail SMTP server information. You really set this, and the scheduling up in the Docker Run command for Watchtower, but it's valuable to get the information together before you enter the command.

<figure class="kg-card kg-code-card" id="bkmrk--e-watchtower_notifi">```
  -e WATCHTOWER_NOTIFICATIONS=email \
  -e WATCHTOWER_NOTIFICATION_EMAIL_FROM=fromaddress@gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_TO=toaddress@gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=fromaddress@gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=app_password \
  -e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=2 \
```

<figcaption>While I add this for convenience, it's always valuable to check the Official Watchtower site for up to date usage information.</figcaption></figure>FROM - your email address  
TO - your email address  
SERVER - your SMTP server (I generally recommend against Gmail due to difficulties in getting it to work, but feel free tot ry it).  
PORT - depends on your SMTP server / host  
USER - usually your full email address, but could be the part before the @ symbol, depends on your SMTP server / host  
PASSWORD - your email password

Leave the NOTIFICATIONS and DELAY values as they are.

### Cron for Scheduling the Checks

Watchtower uses a 6 position cron syntax to schedule the checks.

```
 *	*	*	*	*	*
 s	m	h	D	W	M
 s = seconds
 m = minutes
 h = hours
 D = Days
 W = Weeks
 M = Months
```

So, we can set our schedule in many ways. I messed up and misunderstood when I did the video, and initially set it to run every 5 seconds. Don't do that...trust me!

Let's say we want to run every hour of every day:

```
0	0	*	*	*	*
```

This will run every hour.

I run mine every day with

```
0	0	0	*/1	*	*
```

If you want to run every week you could change it to:

```
0	0	0	*	*/1	*
```

And so on.

## Install Watchtower

Now that we have all of our information together, we can install Watchtwoer and get it running confidently.

We'll use this command:

```
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=email \
  -e WATCHTOWER_NOTIFICATION_EMAIL_FROM=fromaddress@gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_TO=toaddress@gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=fromaddress@gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=app_password \
  -e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=2 \
  -e WATCHTOWER_SCHEDULE="0 0 0 */1 * *"
  containrrr/watchtower
```

of course filling in your appropriate Email information in the fileds shown.

Press Enter / return, and let it run.

You should see watchtower startup, and you can verify it's running in Portainer, or via the `docker ps` command.

You can also check the logs in Portainer, or via the `docker logs watchtower` command.

It should also send an immediate email (or within a few minutes). Once you have it, you'll know things are probably setup correctly.

Just sit back and wait for the updates, and notifications.

# Watchtower Service Documentation

## Overview

**Watchtower** is a lightweight and powerful tool designed to automate the process of keeping Docker containers up-to-date. By monitoring the Docker socket, Watchtower checks for updates to container images, pulls the latest versions, and restarts the containers with minimal intervention. This automation is especially useful in home lab environments or production setups, reducing the need for manual updates and ensuring containers remain secure and current.

---

## Key Features

1. **Automated Updates**: Automatically checks for and applies updates to running containers.
2. **Scheduled Checks**: Allows for configurable schedules to avoid disruption during peak usage times.
3. **Resource Optimization**: Cleans up outdated images after updates to conserve disk space.
4. **Ease of Use**: Minimal setup and configuration required for seamless integration with Docker.

---

## Docker Compose Configuration

Here’s the `docker-compose.yml` file for deploying Watchtower:

```yaml
services:

watchtower:

image: containrrr/watchtower
container_name: 'watchtower'
restart: 'unless-stopped'
environment:
	TZ: America/New_York
	WATCHTOWER_CLEANUP: true
	WATCHTOWER_INCLUDE_RESTARTING: true
	WATCHTOWER_ROLLING_RESTARTING: true
	WATCHTOWER_SCHEDULE: "0 0 4 * * *"
	WATCHTOWER_INCLUDE_STOPPED: true
	WATCHTOWER_NOTIFICATIONS: email
	WATCHTOWER_NOTIFICATIONS_HOSTNAME: "Docker Server"
	WATCHTOWER_NOTIFICATION_EMAIL_FROM: miker@mmcfetridge.net
	WATCHTOWER_NOTIFICATION_EMAIL_TO: miker@mmcfetridge.net
	WATCHTOWER_NOTIFICATION_EMAIL_SERVER: mail.mmcfetridge.net
	WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587
	WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: miker@mmcfetridge.net
	WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: "password"
security_opt:
- no-new-privileges:true
volumes:
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- /var/run/docker.sock:/var/run/docker.sock
- command: --cleanup --schedule "0 3 * * *"
```

### Configuration Explanation

1. **Image**:  
    The `containrrr/watchtower` image is the official Watchtower image, ensuring reliability and access to the latest features.
    
2. **Container Name**:  
    Naming the container `watchtower` simplifies management and identification in your Docker environment.
    
3. **Restart Policy**:  
    The `restart: unless-stopped` policy ensures that Watchtower stays active and restarts automatically after reboots or crashes.
    
4. **Volumes**:
    
    - **`/var/run/docker.sock`**: Provides Watchtower access to Docker's API, enabling it to monitor and manage other containers.
5. **Command**:
    
    - `--cleanup`: Automatically removes outdated images after successful updates to save storage space.
    - `--schedule "0 3 * * *"`: Configures Watchtower to check for updates daily at 3:00 AM UTC, a time chosen to minimize impact on regular operations.

---

## Deployment Instructions

1. **Save the Configuration**:  
    Save the provided `docker-compose.yml` file to a directory of your choice.
    
2. **Deploy the Service**:  
    Start the Watchtower service with the following command:
    
    ```bash
    docker-compose up -d
    ```
    
3. **Verify the Deployment**:  
    Check that Watchtower is running:
    
    ```bash
    docker ps
    ```
    
4. **Monitor Logs**:  
    Review the logs to ensure that Watchtower is functioning as expected:
    
    ```bash
    docker logs watchtower
    ```
    

---

## Security Considerations

- **Docker Socket Access**:  
    The Docker socket grants full access to the Docker API. Restrict access to the Docker host to trusted users and monitor logs for unusual activity.
    
- **Backup Before Updates**:  
    While Watchtower is reliable, always maintain backups of critical containers and data to mitigate risks associated with updates.
    
- **Testing in Staging**:  
    If possible, test updates in a staging environment before applying them to production systems.
    

---

## Benefits of Using Watchtower

- **Efficiency**: Automates repetitive update tasks, saving time and effort.
- **Reliability**: Ensures containers are consistently running the latest and most secure versions.
- **Resource Optimization**: Prevents outdated images from consuming unnecessary storage space.
- **Convenience**: Minimal configuration required for ongoing maintenance of your Docker environment.

---

## Advanced Options

- **Excluding Containers**:  
    You can exclude specific containers from being updated by adding the `com.centurylinklabs.watchtower.enable` label set to `false` in their configurations:
    
    ```yaml
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
    ```
    
- **Notification Integrations**:  
    Configure Watchtower to send update notifications to services like Slack, email, or webhooks for better monitoring:
    
    ```yaml
    environment:
      WATCHTOWER_NOTIFICATIONS: "slack"
      WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: "<your-slack-webhook-url>"
    ```
    

---

By integrating Watchtower into your home lab or production environment, you can maintain an up-to-date and secure container ecosystem with minimal manual intervention. It’s a set-it-and-forget-it tool that streamlines container management, allowing you to focus on other aspects of your infrastructure.