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:

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.

  -e \
  -e \
  -e \
  -e \
While I add this for convenience, it's always valuable to check the Official Watchtower site for up to date usage information.

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 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 \
  -e \
  -e \
  -e \
  -e WATCHTOWER_SCHEDULE="0 0 0 */1 * *"

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.