<p>In the example above, watchtower will execute an upgrade attempt on the containers named "nginx" and "redis". Using this mode will enable debugging output showing all actions performed, as usage is intended for interactive users. Once the attempt is completed, the container will exit and remove itself due to the <code>--rm</code> flag.</p>
<p>In the example above, watchtower will execute an upgrade attempt on the containers named "nginx" and "redis". Using this mode will enable debugging output showing all actions performed, as usage is intended for interactive users. Once the attempt is completed, the container will exit and remove itself due to the <code>--rm</code> flag.</p>
<p>When no arguments are specified, watchtower will monitor all running containers.</p>
<p>When no arguments are specified, watchtower will monitor all running containers.</p>
<p>Sets the time zone to be used by WatchTower's logs and the optional Cron scheduling argument (--schedule). If this environment variable is not set, Watchtower will use the default time zone: UTC.
<p>Sets the time zone to be used by WatchTower's logs and the optional Cron scheduling argument (--schedule). If this environment variable is not set, Watchtower will use the default time zone: UTC.
To find out the right value, see <ahref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">this list</a>, find your location and use the value in <em>TZ Database Name</em>, e.g <em>Europe/Rome</em>. The timezone can alternatively be set by volume mounting your hosts /etc/localtime file. <code>-v /etc/localtime:/etc/localtime:ro</code></p>
To find out the right value, see <ahref="https://en.wikipedia.org/wiki/List_of_tz_database_time_zones">this list</a>, find your location and use the value in <em>TZ Database Name</em>, e.g <em>Europe/Rome</em>. The timezone can alternatively be set by volume mounting your hosts /etc/localtime file. <code>-v /etc/localtime:/etc/localtime:ro</code></p>
<p>Removes old images after updating. When this flag is specified, watchtower will remove the old image after restarting a container with a new image. Use this option to prevent the accumulation of orphaned images on your system as containers are updated.</p>
<p>Removes old images after updating. When this flag is specified, watchtower will remove the old image after restarting a container with a new image. Use this option to prevent the accumulation of orphaned images on your system as containers are updated.</p>
<p>Removes attached volumes after updating. When this flag is specified, watchtower will remove all attached volumes from the container before restarting with a new image. Use this option to force new volumes to be populated as containers are updated.</p>
<p>Removes attached volumes after updating. When this flag is specified, watchtower will remove all attached volumes from the container before restarting with a new image. Use this option to force new volumes to be populated as containers are updated.</p>
<p>Poll interval (in seconds). This value controls how frequently watchtower will poll for new images. Either <code>--schedule</code> or a poll interval can be defined, but not both.</p>
<p>Poll interval (in seconds). This value controls how frequently watchtower will poll for new images. Either <code>--schedule</code> or a poll interval can be defined, but not both.</p>
<h2id="filter_by_disable_label">Filter by disable label<aclass="headerlink"href="#filter_by_disable_label"title="Permanent link">¶</a></h2>
<h2id="filter_by_disable_label">Filter by disable label<aclass="headerlink"href="#filter_by_disable_label"title="Permanent link">¶</a></h2>
<p><strong>Do not</strong> update containers that have <code>com.centurylinklabs.watchtower.enable</code> label set to false and no <code>--label-enable</code> argument is passed. Note that only one or the other (targeting by enable label) can be used at the same time to target containers.</p>
<p><strong>Do not</strong> update containers that have <code>com.centurylinklabs.watchtower.enable</code> label set to false and
no <code>--label-enable</code> argument is passed. Note that only one or the other (targeting by enable label) can be
<p>Will only monitor for new images, send notifications and invoke the <ahref="https://containrrr.dev/watchtower/lifecycle-hooks/">pre-check/post-check hooks</a>, but will <strong>not</strong> update the containers.</p>
<p>Will only monitor for new images, send notifications and invoke
<blockquote>
the <ahref="https://containrrr.dev/watchtower/lifecycle-hooks/">pre-check/post-check hooks</a>, but will <strong>not</strong> update the
<p><strong>⚠️ Please note</strong></p>
containers.</p>
<p>Due to Docker API limitations the latest image will still be pulled from the registry.</p>
<p>!!! note Due to Docker API limitations the latest image will still be pulled from the registry.<br/>
</blockquote>
The HEAD digest checks allows watchtower to skip pulling when there are no changes, but to know <em>what</em> has changed it
<p>Note that monitor-only can also be specified on a per-container basis with the <code>com.centurylinklabs.watchtower.monitor-only</code> label set on those containers.</p>
<p>Note that monitor-only can also be specified on a per-container basis with the <code>com.centurylinklabs.watchtower.monitor-only</code> label set on those containers.</p>
<h2id="without_pulling_new_images">Without pulling new images<aclass="headerlink"href="#without_pulling_new_images"title="Permanent link">¶</a></h2>
<h2id="without_pulling_new_images">Without pulling new images<aclass="headerlink"href="#without_pulling_new_images"title="Permanent link">¶</a></h2>
<p>Do not pull new images. When this flag is specified, watchtower will not attempt to pull
<p>Do not pull new images. When this flag is specified, watchtower will not attempt to pull
new images from the registry. Instead it will only monitor the local image cache for changes.
new images from the registry. Instead it will only monitor the local image cache for changes.
Use this option if you are building new images directly on the Docker host without pushing
Use this option if you are building new images directly on the Docker host without pushing
<h2id="http_api_mode">HTTP API Mode<aclass="headerlink"href="#http_api_mode"title="Permanent link">¶</a></h2>
<h2id="http_api_mode">HTTP API Mode<aclass="headerlink"href="#http_api_mode"title="Permanent link">¶</a></h2>
<p>Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. For details see <ahref="https://containrrr.github.io/watchtower/http-api-mode">HTTP API</a>.</p>
<p>Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request.
<h2id="filter_by_scope">Filter by scope<aclass="headerlink"href="#filter_by_scope"title="Permanent link">¶</a></h2>
<h2id="filter_by_scope">Filter by scope<aclass="headerlink"href="#filter_by_scope"title="Permanent link">¶</a></h2>
<p>Update containers that have a <code>com.centurylinklabs.watchtower.scope</code> label set with the same value as the given argument. This enables <ahref="https://containrrr.github.io/watchtower/running-multiple-instances">running multiple instances</a>.</p>
<p>Update containers that have a <code>com.centurylinklabs.watchtower.scope</code> label set with the same value as the given argument.
<p><ahref="https://pkg.go.dev/github.com/robfig/cron@v1.2.0?tab=doc#hdr-CRON_Expression_Format">Cron expression</a> in 6 fields (rather than the traditional 5) which defines when and how often to check for new images. Either <code>--interval</code> or the schedule expression
<p><ahref="https://pkg.go.dev/github.com/robfig/cron@v1.2.0?tab=doc#hdr-CRON_Expression_Format">Cron expression</a> in 6 fields (rather than the traditional 5) which defines when and how often to check for new images. Either <code>--interval</code> or the schedule expression
can be defined, but not both. An example: <code>--schedule "0 0 4 * * *"</code></p>
can be defined, but not both. An example: <code>--schedule "0 0 4 * * *"</code></p>
<h2id="wait_until_timeout">Wait until timeout<aclass="headerlink"href="#wait_until_timeout"title="Permanent link">¶</a></h2>
<h2id="wait_until_timeout">Wait until timeout<aclass="headerlink"href="#wait_until_timeout"title="Permanent link">¶</a></h2>
<p>Timeout before the container is forcefully stopped. When set, this option will change the default (<code>10s</code>) wait time to the given value. An example: <code>--stop-timeout 30s</code> will set the timeout to 30 seconds.</p>
<p>Timeout before the container is forcefully stopped. When set, this option will change the default (<code>10s</code>) wait time to the given value. An example: <code>--stop-timeout 30s</code> will set the timeout to 30 seconds.</p>
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.enable<spanclass="o">=</span><spanclass="nb">false</span> someimage
<divclass="highlight"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.enable<spanclass="o">=</span><spanclass="nb">false</span> someimage
</code></pre></div>
</code></pre></div>
<p>If you need to <ahref="https://containrrr.github.io/watchtower/arguments/#filter_by_enable_label">include only containers with the enable label</a>, pass the <code>--label-enable</code> flag or the <code>WATCHTOWER_LABEL_ENABLE</code> environment variable on startup and set the <em>com.centurylinklabs.watchtower.enable</em> label with a value of <code>true</code> for the containers you want to watch.</p>
<p>If you need to <ahref="https://containrrr.github.io/watchtower/arguments/#filter_by_enable_label">include only containers with the enable label</a>, pass the <code>--label-enable</code> flag or the <code>WATCHTOWER_LABEL_ENABLE</code> environment variable on startup and set the <em>com.centurylinklabs.watchtower.enable</em> label with a value of <code>true</code> for the containers you want to watch.</p>
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.enable<spanclass="o">=</span><spanclass="nb">true</span> someimage
<divclass="highlight"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.enable<spanclass="o">=</span><spanclass="nb">true</span> someimage
</code></pre></div>
</code></pre></div>
<p>If you wish to create a monitoring scope, you will need to <ahref="https://containrrr.github.io/watchtower/running-multiple-instances">run multiple instances and set a scope for each of them</a>.</p>
<p>If you wish to create a monitoring scope, you will need to <ahref="https://containrrr.github.io/watchtower/running-multiple-instances">run multiple instances and set a scope for each of them</a>.</p>
<p>Watchtower filters running containers by testing them against each configured criteria. A container is monitored if all criteria are met. For example:
<p>Watchtower filters running containers by testing them against each configured criteria. A container is monitored if all criteria are met. For example:
- If a container's name is on the monitoring name list (not empty <code>--name</code> argument) but it is not enabled (<em>centurylinklabs.watchtower.enable=false</em>), it won't be monitored;
- If a container's name is on the monitoring name list (not empty <code>--name</code> argument) but it is not enabled (<em>centurylinklabs.watchtower.enable=false</em>), it won't be monitored;
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.monitor-only<spanclass="o">=</span><spanclass="nb">true</span> someimage
<divclass="highlight"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.monitor-only<spanclass="o">=</span><spanclass="nb">true</span> someimage
</code></pre></div>
</code></pre></div>
<p>When the label is specified on a container, watchtower treats that container exactly as if <ahref="https://containrrr.dev/watchtower/arguments/#without_updating_containers"><code>WATCHTOWER_MONITOR_ONLY</code></a> was set, but the effect is limited to the individual container. </p>
<p>When the label is specified on a container, watchtower treats that container exactly as if <ahref="https://containrrr.dev/watchtower/arguments/#without_updating_containers"><code>WATCHTOWER_MONITOR_ONLY</code></a> was set, but the effect is limited to the individual container. </p>
<p>Notice that there is an environment variable named WATCHTOWER_HTTP_API_TOKEN. To prevent external services from accidentally triggering image updates, all of the requests have to contain a "Token" field, valued as the token defined in WATCHTOWER_HTTP_API_TOKEN, in their headers. In this case, there is a port bind to the host machine, allowing to request localhost:8080 to reach Watchtower. The following <code>curl</code> command would trigger an image update:</p>
<p>Notice that there is an environment variable named WATCHTOWER_HTTP_API_TOKEN. To prevent external services from accidentally triggering image updates, all of the requests have to contain a "Token" field, valued as the token defined in WATCHTOWER_HTTP_API_TOKEN, in their headers. In this case, there is a port bind to the host machine, allowing to request localhost:8080 to reach Watchtower. The following <code>curl</code> command would trigger an image update:</p>
<p>With watchtower you can update the running version of your containerized app simply by pushing a new image to the Docker Hub or your own image registry. Watchtower will pull down your new image, gracefully shut down your existing container and restart it with the same options that were used when it was deployed initially. Run the watchtower container with the following command:</p>
<p>With watchtower you can update the running version of your containerized app simply by pushing a new image to the Docker
<divclass="codehilite"><pre><span></span><code>$ docker run -d <spanclass="se">\</span>
Hub or your own image registry. Watchtower will pull down your new image, gracefully shut down your existing container
--name watchtower <spanclass="se">\</span>
and restart it with the same options that were used when it was deployed initially. Run the watchtower container with
<p>Watchtower is an application that will monitor your running Docker containers and watch for changes to the images that those containers were originally started from. If watchtower detects that an image has changed, it will automatically restart the container using the new image.</p>
<p>Watchtower is an application that will monitor your running Docker containers and watch for changes to the images that those containers were originally started from. If watchtower detects that an image has changed, it will automatically restart the container using the new image.</p>
<p>With watchtower you can update the running version of your containerized app simply by pushing a new image to the Docker Hub or your own image registry. Watchtower will pull down your new image, gracefully shut down your existing container and restart it with the same options that were used when it was deployed initially.</p>
<p>With watchtower you can update the running version of your containerized app simply by pushing a new image to the Docker Hub or your own image registry. Watchtower will pull down your new image, gracefully shut down your existing container and restart it with the same options that were used when it was deployed initially.</p>
<p>For example, let's say you were running watchtower along with an instance of <em>centurylink/wetty-cli</em> image:</p>
<p>For example, let's say you were running watchtower along with an instance of <em>centurylink/wetty-cli</em> image:</p>
967848166a45 centurylink/wetty-cli Up <spanclass="m">10</span> minutes <spanclass="m">0</span>.0.0.0:8080->3000/tcp wetty
967848166a45 centurylink/wetty-cli Up 10 minutes 0.0.0.0:8080->3000/tcp wetty
6cc4d2a9d1a5 containrrr/watchtower Up <spanclass="m">15</span> minutes watchtower
6cc4d2a9d1a5 containrrr/watchtower Up 15 minutes watchtower
</code></pre></div>
</code></pre></div>
<p>Every few minutes watchtower will pull the latest <em>centurylink/wetty-cli</em> image and compare it to the one that was used to run the "wetty" container. If it sees that the image has changed it will stop/remove the "wetty" container and then restart it using the new image and the same <code>docker run</code> options that were used to start the container initially (in this case, that would include the <code>-p 8080:3000</code> port mapping).</p>
<p>Every few minutes watchtower will pull the latest <em>centurylink/wetty-cli</em> image and compare it to the one that was used to run the "wetty" container. If it sees that the image has changed it will stop/remove the "wetty" container and then restart it using the new image and the same <code>docker run</code> options that were used to start the container initially (in this case, that would include the <code>-p 8080:3000</code> port mapping).</p>
<h2id="executing_commands_before_and_after_updating">Executing commands before and after updating<aclass="headerlink"href="#executing_commands_before_and_after_updating"title="Permanent link">¶</a></h2>
<h2id="executing_commands_before_and_after_updating">Executing commands before and after updating<aclass="headerlink"href="#executing_commands_before_and_after_updating"title="Permanent link">¶</a></h2>
<blockquote>
<divclass="admonition note">
<p><strong>DO NOTE</strong>: These are shell commands executed with <code>sh</code>, and therefore require the
<pclass="admonition-title">Note</p>
container to provide the <code>sh</code> executable.</p>
<p>These are shell commands executed with <code>sh</code>, and therefore require the container to provide the <code>sh</code>
</blockquote>
executable.</p>
</div>
<p>It is possible to execute <em>pre/post-check</em> and <em>pre/post-update</em> commands
<p>It is possible to execute <em>pre/post-check</em> and <em>pre/post-update</em> commands
<strong>inside</strong> every container updated by watchtower.</p>
<strong>inside</strong> every container updated by watchtower.</p>
<ul>
<ul>
@ -608,22 +609,21 @@ container to provide the <code>sh</code> executable.</p>
</tr>
</tr>
</tbody>
</tbody>
</table>
</table>
<p>These labels can be declared as instructions in a Dockerfile (with some example .sh files):</p>
<p>These labels can be declared as instructions in a Dockerfile (with some example .sh files) or be specified as part of
<p>This feature was added in v1.0.4 and is still considered experimental.
<p>This feature was added in v1.0.4 and is still considered experimental. If you notice any strange behavior, please raise
If you notice any strange behavior, please raise a ticket in the repository issues.</p>
a ticket in the repository issues.</p>
</blockquote>
</div>
<p>Metrics can be used to track how Watchtower behaves over time.</p>
<p>Metrics can be used to track how Watchtower behaves over time.</p>
<p>To use this feature, you have to set an <ahref="../arguments/#http-api-token">API token</a> and <ahref="../arguments/#http-api-metrics">enable the metrics API</a>,
<p>To use this feature, you have to set an <ahref="../arguments/#http-api-token">API token</a> and <ahref="../arguments/#http-api-metrics">enable the metrics API</a>,
as well as creating a port mapping for your container for port <code>8080</code>.</p>
as well as creating a port mapping for your container for port <code>8080</code>.</p>
<p>Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging system, <ahref="http://github.com/sirupsen/logrus">logrus</a>.
<p>Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging
The types of notifications to send are set by passing a comma-separated list of values to the <code>--notifications</code> option (or corresponding environment variable <code>WATCHTOWER_NOTIFICATIONS</code>), which has the following valid values:</p>
system, <ahref="http://github.com/sirupsen/logrus">logrus</a>. The types of notifications to send are set by passing a
comma-separated list of values to the <code>--notifications</code> option
(or corresponding environment variable <code>WATCHTOWER_NOTIFICATIONS</code>), which has the following valid values:</p>
<ul>
<ul>
<li><code>email</code> to send notifications via e-mail</li>
<li><code>email</code> to send notifications via e-mail</li>
<li><code>slack</code> to send notifications through a Slack webhook</li>
<li><code>slack</code> to send notifications through a Slack webhook</li>
@ -594,11 +596,17 @@ The types of notifications to send are set by passing a comma-separated list of
<li><code>gotify</code> to send notifications via Gotify</li>
<li><code>gotify</code> to send notifications via Gotify</li>
<li><code>shoutrrr</code> to send notifications via <ahref="https://github.com/containrrr/shoutrrr">containrrr/shoutrrr</a></li>
<li><code>shoutrrr</code> to send notifications via <ahref="https://github.com/containrrr/shoutrrr">containrrr/shoutrrr</a></li>
</ul>
</ul>
<blockquote>
<divclass="admonition note">
<p>There is currently a <ahref="https://github.com/spf13/viper/issues/380">bug</a> in Viper, which prevents comma-separated slices to be used when using the environment variable. A workaround is available where we instead put quotes around the environment variable value and replace the commas with spaces, as <code>WATCHTOWER_NOTIFICATIONS="slack msteams"</code></p>
<pclass="admonition-title">Using multiple notifications with environment variables</p>
<p>If you're a <code>docker-compose</code> user, make sure to specify environment variables' values in your <code>.yml</code> file without double quotes (<code>"</code>).</p>
<p>There is currently a bug in Viper (<aclass="magiclink magiclink-github magiclink-issue"href="https://github.com/spf13/viper/issues/380"title="GitHub Issue: spf13/viper#380">spf13/viper#380</a>), which prevents comma-separated slices to
<p>This prevents unexpected errors when watchtower starts.</p>
be used when using the environment variable.<br/>
</blockquote>
A workaround is available where we instead put quotes around the environment variable value and replace the commas with
<li><code>--notifications-level</code> (env. <code>WATCHTOWER_NOTIFICATIONS_LEVEL</code>): Controls the log level which is used for the notifications. If omitted, the default log level is <code>info</code>. Possible values are: <code>panic</code>, <code>fatal</code>, <code>error</code>, <code>warn</code>, <code>info</code>, <code>debug</code> or <code>trace</code>.</li>
<li><code>--notifications-level</code> (env. <code>WATCHTOWER_NOTIFICATIONS_LEVEL</code>): Controls the log level which is used for the notifications. If omitted, the default log level is <code>info</code>. Possible values are: <code>panic</code>, <code>fatal</code>, <code>error</code>, <code>warn</code>, <code>info</code>, <code>debug</code> or <code>trace</code>.</li>
@ -619,7 +627,7 @@ The types of notifications to send are set by passing a comma-separated list of
<li><code>--notification-email-subjecttag</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_SUBJECTTAG</code>): Prefix to include in the subject tag. Useful when running multiple watchtowers.</li>
<li><code>--notification-email-subjecttag</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_SUBJECTTAG</code>): Prefix to include in the subject tag. Useful when running multiple watchtowers.</li>
</ul>
</ul>
<p>Example:</p>
<p>Example:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<p>The previous example assumes, that you already have an SMTP server up and running you can connect to. If you don't or you want to bring up watchtower with your own simple SMTP relay the following <code>docker-compose.yml</code> might be a good start for you.</p>
<p>The previous example assumes, that you already have an SMTP server up and running you can connect to. If you don't or you want to bring up watchtower with your own simple SMTP relay the following <code>docker-compose.yml</code> might be a good start for you.</p>
<p>The following example assumes, that your domain is called <code>your-domain.com</code> and that you are going to use a certificate valid for <code>smtp.your-domain.com</code>. This hostname has to be used as <code>WATCHTOWER_NOTIFICATION_EMAIL_SERVER</code> otherwise the TLS connection is going to fail with <code>Failed to send notification email</code> or <code>connect: connection refused</code>. We also have to add a network for this setup in order to add an alias to it. If you also want to enable DKIM or other features on the SMTP server, you will find more information at <ahref="https://hub.docker.com/r/freinet/postfix-relay">freinet/postfix-relay</a>.</p>
<p>The following example assumes, that your domain is called <code>your-domain.com</code> and that you are going to use a certificate valid for <code>smtp.your-domain.com</code>. This hostname has to be used as <code>WATCHTOWER_NOTIFICATION_EMAIL_SERVER</code> otherwise the TLS connection is going to fail with <code>Failed to send notification email</code> or <code>connect: connection refused</code>. We also have to add a network for this setup in order to add an alias to it. If you also want to enable DKIM or other features on the SMTP server, you will find more information at <ahref="https://hub.docker.com/r/freinet/postfix-relay">freinet/postfix-relay</a>.</p>
<p>If watchtower is monitoring the same Docker daemon under which the watchtower container itself is running (i.e. if you volume-mounted <em>/var/run/docker.sock</em> into the watchtower container) then it has the ability to update itself. If a new version of the <em>containrrr/watchtower</em> image is pushed to the Docker Hub, your watchtower will pull down the new image and restart itself automatically.</p>
<p>If watchtower is monitoring the same Docker daemon under which the watchtower container itself is running (i.e. if you volume-mounted <em>/var/run/docker.sock</em> into the watchtower container) then it has the ability to update itself. If a new version of the <em>containrrr/watchtower</em> image is pushed to the Docker Hub, your watchtower will pull down the new image and restart itself automatically.</p>
<p>To receive notifications in Slack, add <code>slack</code> to the <code>--notifications</code> option or the <code>WATCHTOWER_NOTIFICATIONS</code> environment variable.</p>
<p>To receive notifications in Slack, add <code>slack</code> to the <code>--notifications</code> option or the <code>WATCHTOWER_NOTIFICATIONS</code> environment variable.</p>
@ -688,28 +693,23 @@ The types of notifications to send are set by passing a comma-separated list of
<p>Other, optional, variables include:</p>
<p>Other, optional, variables include:</p>
<ul>
<ul>
<li><code>--notification-slack-channel</code> (env. <code>WATCHTOWER_NOTIFICATION_SLACK_CHANNEL</code>): A string which overrides the webhook's default channel. Example: #my-custom-channel.</li>
<li><code>--notification-slack-channel</code> (env. <code>WATCHTOWER_NOTIFICATION_SLACK_CHANNEL</code>): A string which overrides the webhook's default channel. Example: #my-custom-channel.</li>
<li><code>--notification-slack-icon-emoji</code> (env. <code>WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI</code>): An <ahref="https://www.webpagefx.com/tools/emoji-cheat-sheet/">emoji code</a> string to use in place of the default icon.</li>
<li><code>--notification-slack-icon-url</code> (env. <code>WATCHTOWER_NOTIFICATION_SLACK_ICON_URL</code>): An icon image URL string to use in place of the default icon.</li>
</ul>
</ul>
<p>Example:</p>
<p>Example:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<p>To receive notifications in MSTeams channel, add <code>msteams</code> to the <code>--notifications</code> option or the <code>WATCHTOWER_NOTIFICATIONS</code> environment variable.</p>
<p>To receive notifications in MSTeams channel, add <code>msteams</code> to the <code>--notifications</code> option or the <code>WATCHTOWER_NOTIFICATIONS</code> environment variable.</p>
<p>Additionally, you should set the MSTeams webhook URL using the <code>--notification-msteams-hook</code> option or the <code>WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL</code> environment variable. This option can also reference a file, in which case the contents of the file are used.</p>
<p>Additionally, you should set the MSTeams webhook URL using the <code>--notification-msteams-hook</code> option or the <code>WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL</code> environment variable. This option can also reference a file, in which case the contents of the file are used.</p>
<p>MSTeams notifier could send keys/values filled by <code>log.WithField</code> or <code>log.WithFields</code> as MSTeams message facts. To enable this feature add <code>--notification-msteams-data</code> flag or set <code>WATCHTOWER_NOTIFICATION_MSTEAMS_USE_LOG_DATA=true</code> environment variable.</p>
<p>MSTeams notifier could send keys/values filled by <code>log.WithField</code> or <code>log.WithFields</code> as MSTeams message facts. To enable this feature add <code>--notification-msteams-data</code> flag or set <code>WATCHTOWER_NOTIFICATION_MSTEAMS_USE_LOG_DATA=true</code> environment variable.</p>
<p>Example:</p>
<p>Example:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<p><code>-e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN</code> or <code>--notification-gotify-token</code> can also reference a file, in which case the contents of the file are used.</p>
<p><code>-e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN</code> or <code>--notification-gotify-token</code> can also reference a file, in which case the contents of the file are used.</p>
<p>If you want to disable TLS verification for the Gotify instance, you can use either <code>-e WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY=true</code> or <code>--notification-gotify-tls-skip-verify</code>.</p>
<p>If you want to disable TLS verification for the Gotify instance, you can use either <code>-e WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY=true</code> or <code>--notification-gotify-tls-skip-verify</code>.</p>
@ -736,16 +734,26 @@ The types of notifications to send are set by passing a comma-separated list of
<ul>
<ul>
<li><code>--notification-url</code> (env. <code>WATCHTOWER_NOTIFICATION_URL</code>): The shoutrrr service URL to be used.</li>
<li><code>--notification-url</code> (env. <code>WATCHTOWER_NOTIFICATION_URL</code>): The shoutrrr service URL to be used.</li>
</ul>
</ul>
<p>Go to <ahref="https://containrrr.github.io/shoutrrr/services/overview">containrrr.github.io/shoutrrr/services/overview</a> to learn more about the different service URLs you can use.
<p>Go to <ahref="https://containrrr.github.io/shoutrrr/services/overview">containrrr.github.io/shoutrrr/services/overview</a> to
You can define multiple services by space separating the URLs. (See example below)</p>
learn more about the different service URLs you can use. You can define multiple services by space separating the
URLs. (See example below)</p>
<p>You can customize the message posted by setting a template.</p>
<p>You can customize the message posted by setting a template.</p>
<ul>
<ul>
<li><code>--notification-template</code> (env. <code>WATCHTOWER_NOTIFICATION_TEMPLATE</code>): The template used for the message.</li>
<li><code>--notification-template</code> (env. <code>WATCHTOWER_NOTIFICATION_TEMPLATE</code>): The template used for the message.</li>
</ul>
</ul>
<p>The template is a Go <ahref="https://golang.org/pkg/text/template/">template</a> and the you format a list of <ahref="https://pkg.go.dev/github.com/sirupsen/logrus?tab=doc#Entry">log entries</a>.</p>
<p>The template is a Go <ahref="https://golang.org/pkg/text/template/">template</a> and that format a list
<p>The default value if not set is <code>{{range .}}{{.Message}}{{println}}{{end}}</code>. The example below uses a template that also outputs timestamp and log level.</p>
of <ahref="https://pkg.go.dev/github.com/sirupsen/logrus?tab=doc#Entry">log entries</a>.</p>
<p>The default value if not set is <code>{{range .}}{{.Message}}{{println}}{{end}}</code>. The example below uses a template that also
outputs timestamp and log level.</p>
<divclass="admonition tip">
<pclass="admonition-title">Custom date format</p>
<p>If you want to adjust the date/time format it must show how the
<ahref="https://golang.org/pkg/time/#pkg-constants">reference time</a> (<em>Mon Jan 2 15:04:05 MST 2006</em>) would be displayed in your
custom format.<br/>
i.e. The day of the year has to be 1, the month has to be 2 (february), the hour 3 (or 15 for 24h time) etc.</p>
</div>
<p>Example:</p>
<p>Example:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<pclass="admonition-title">Username and Password for GCloud</p>
<h3id="i_username_and_password_for_gcloud">ℹ️ Username and Password for GCloud<aclass="headerlink"href="#i_username_and_password_for_gcloud"title="Permanent link">¶</a></h3>
<p>For gcloud, we'll use <code>_json_key</code> as our username and the content of <code>gcloudauth.json</code> as the password.
<p>For gcloud, we'll use <code>_json_key</code> as our username and the content
<p>By default, watchtower will look for the <code>config.json</code> file in <code>/</code>, but this can be changed by setting the <code>DOCKER_CONFIG</code> environment variable to the directory path where your config is located. This is useful for setups where the config.json file is changed while the watchtower instance is running, as the changes will not be picked up for a mounted file if the inode changes.
<p>By default, watchtower will look for the <code>config.json</code> file in <code>/</code>, but this can be changed by setting the <code>DOCKER_CONFIG</code> environment variable to the directory path where your config is located. This is useful for setups where the config.json file is changed while the watchtower instance is running, as the changes will not be picked up for a mounted file if the inode changes.
<li>Use the following commands to build the aws-ecr-dock-cred-helper and store it's output in a volume:</li>
<li>Use the following commands to build the aws-ecr-dock-cred-helper and store it's output in a volume:</li>
</ol>
</ol>
<p>```shell script</p>
<divclass="highlight"><pre><span></span><code><spanclass="c1"># Create a volume to store the command (once built)</span>
<h1id="create_a_volume_to_store_the_command_once_built">Create a volume to store the command (once built)<aclass="headerlink"href="#create_a_volume_to_store_the_command_once_built"title="Permanent link">¶</a></h1>
docker volume create helper
<p>docker volume create helper </p>
<h1id="build_the_container">Build the container<aclass="headerlink"href="#build_the_container"title="Permanent link">¶</a></h1>
<spanclass="c1"># Build the container</span>
<p>docker build -t aws-ecr-dock-cred-helper .</p>
docker build -t aws-ecr-dock-cred-helper .
<h1id="build_the_command_and_store_it_in_the_new_volume_in_the_gobin_directory">Build the command and store it in the new volume in the /go/bin directory.<aclass="headerlink"href="#build_the_command_and_store_it_in_the_new_volume_in_the_gobin_directory"title="Permanent link">¶</a></h1>
<p>docker run -d --rm --name aws-cred-helper --volume helper:/go/bin aws-ecr-dock-cred-helper</p>
<p>By default, watchtower is set-up to monitor the local Docker daemon (the same daemon running the watchtower container itself). However, it is possible to configure watchtower to monitor a remote Docker endpoint. When starting the watchtower container you can specify a remote Docker endpoint with either the <code>--host</code> flag or the <code>DOCKER_HOST</code> environment variable:</p>
<p>By default, watchtower is set-up to monitor the local Docker daemon (the same daemon running the watchtower container itself). However, it is possible to configure watchtower to monitor a remote Docker endpoint. When starting the watchtower container you can specify a remote Docker endpoint with either the <code>--host</code> flag or the <code>DOCKER_HOST</code> environment variable:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
- An instance without a scope will clean up other running instances, even if they have a defined scope;</p>
- An instance without a scope will clean up other running instances, even if they have a defined scope;</p>
<p>To define an instance monitoring scope, use the <code>--scope</code> argument or the <code>WATCHTOWER_SCOPE</code> environment variable on startup and set the <em>com.centurylinklabs.watchtower.scope</em> label with the same value for the containers you want to include in this instance's scope (including the instance itself).</p>
<p>To define an instance monitoring scope, use the <code>--scope</code> argument or the <code>WATCHTOWER_SCOPE</code> environment variable on startup and set the <em>com.centurylinklabs.watchtower.scope</em> label with the same value for the containers you want to include in this instance's scope (including the instance itself).</p>
<p>For example, in a Docker Compose config file:</p>
<p>For example, in a Docker Compose config file:</p>
<p>Watchtower is also capable of connecting to Docker endpoints which are protected by SSL/TLS. If you've used <em>docker-machine</em> to provision your remote Docker host, you simply need to volume mount the certificates generated by <em>docker-machine</em> into the watchtower container and optionally specify <code>--tlsverify</code> flag.</p>
<p>Watchtower is also capable of connecting to Docker endpoints which are protected by SSL/TLS. If you've used <em>docker-machine</em> to provision your remote Docker host, you simply need to volume mount the certificates generated by <em>docker-machine</em> into the watchtower container and optionally specify <code>--tlsverify</code> flag.</p>
<p>The <em>docker-machine</em> certificates for a particular host can be located by executing the <code>docker-machine env</code> command for the desired host (note the values for the <code>DOCKER_HOST</code> and <code>DOCKER_CERT_PATH</code> environment variables that are returned from this command). The directory containing the certificates for the remote host needs to be mounted into the watchtower container at <em>/etc/ssl/docker</em>.</p>
<p>The <em>docker-machine</em> certificates for a particular host can be located by executing the <code>docker-machine env</code> command for the desired host (note the values for the <code>DOCKER_HOST</code> and <code>DOCKER_CERT_PATH</code> environment variables that are returned from this command). The directory containing the certificates for the remote host needs to be mounted into the watchtower container at <em>/etc/ssl/docker</em>.</p>
<p>With the certificates mounted into the watchtower container you need to specify the <code>--tlsverify</code> flag to enable verification of the certificate:</p>
<p>With the certificates mounted into the watchtower container you need to specify the <code>--tlsverify</code> flag to enable verification of the certificate:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<p>When watchtower detects that a running container needs to be updated it will stop the container by sending it a SIGTERM signal.
<p>When watchtower detects that a running container needs to be updated it will stop the container by sending it a SIGTERM signal.
If your container should be shutdown with a different signal you can communicate this to watchtower by setting a label named <em>com.centurylinklabs.watchtower.stop-signal</em> with the value of the desired signal.</p>
If your container should be shutdown with a different signal you can communicate this to watchtower by setting a label named <em>com.centurylinklabs.watchtower.stop-signal</em> with the value of the desired signal.</p>
<p>This label can be coded directly into your image by using the <code>LABEL</code> instruction in your Dockerfile:</p>
<p>This label can be coded directly into your image by using the <code>LABEL</code> instruction in your Dockerfile:</p>
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<p>Or, it can be specified as part of the <code>docker run</code> command line:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.stop-signal<spanclass="o">=</span>SIGHUP someimage
<divclass="highlight"><pre><span></span><code>docker run -d --label<spanclass="o">=</span>com.centurylinklabs.watchtower.stop-signal<spanclass="o">=</span>SIGHUP someimage
<p>Watchtower is itself packaged as a Docker container so installation is as simple as pulling the <code>containrrr/watchtower</code> image. If you are using ARM based architecture, pull the appropriate <code>containrrr/watchtower:armhf-<tag></code> image from the <ahref="https://hub.docker.com/r/containrrr/watchtower/tags/">containrrr Docker Hub</a>.</p>
<p>Watchtower is itself packaged as a Docker container so installation is as simple as pulling the <code>containrrr/watchtower</code> image. If you are using ARM based architecture, pull the appropriate <code>containrrr/watchtower:armhf-<tag></code> image from the <ahref="https://hub.docker.com/r/containrrr/watchtower/tags/">containrrr Docker Hub</a>.</p>
<p>Since the watchtower code needs to interact with the Docker API in order to monitor the running containers, you need to mount <em>/var/run/docker.sock</em> into the container with the <code>-v</code> flag when you run it.</p>
<p>Since the watchtower code needs to interact with the Docker API in order to monitor the running containers, you need to mount <em>/var/run/docker.sock</em> into the container with the <code>-v</code> flag when you run it.</p>
<p>Run the <code>watchtower</code> container with the following command:</p>
<p>Run the <code>watchtower</code> container with the following command:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<p>If pulling images from private Docker registries, supply registry authentication credentials with the environment variables <code>REPO_USER</code> and <code>REPO_PASS</code>
<p>If pulling images from private Docker registries, supply registry authentication credentials with the environment variables <code>REPO_USER</code> and <code>REPO_PASS</code>
or by mounting the host's docker config file into the container (at the root of the container filesystem <code>/</code>).</p>
or by mounting the host's docker config file into the container (at the root of the container filesystem <code>/</code>).</p>
<p>Passing environment variables:</p>
<p>Passing environment variables:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<p>Also check out <ahref="https://stackoverflow.com/a/30494145/7872793">this Stack Overflow answer</a> for more options on how to pass environment variables.</p>
<p>Also check out <ahref="https://stackoverflow.com/a/30494145/7872793">this Stack Overflow answer</a> for more options on how to pass environment variables.</p>
<p>Mounting the host's docker config file:</p>
<p>Mounting the host's docker config file:</p>
<divclass="codehilite"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<divclass="highlight"><pre><span></span><code>docker run -d <spanclass="se">\</span>
<pclass="admonition-title">Changes to config.json while running</p>
<p>NOTE: if you mount <code>config.json</code> in the manner above, changes from the host system will (generally) not be propagated to the running container. Mounting files into the Docker daemon uses bind mounts, which are based on inodes. Most applications (including <code>docker login</code> and <code>vim</code>) will not directly edit the file, but instead make a copy and replace the original file, which results in a new inode which in turn <em>breaks</em> the bind mount. <strong>As a workaround</strong>, you can create a symlink to your <code>config.json</code> file and then mount the symlink in the container. The symlinked file will always have the same inode, which keeps the bind mount intact and will ensure changes to the original file are propagated to the running container (regardless of the inode of the source file!).</p>
<p>If you mount <code>config.json</code> in the manner above, changes from the host system will (generally) not be propagated to the
</blockquote>
running container. Mounting files into the Docker daemon uses bind mounts, which are based on inodes. Most
<p>If you mount the config file as described above, be sure to also prepend the URL for the registry when starting up your watched image (you can omit the https://). Here is a complete docker-compose.yml file that starts up a docker container from a private repo at Docker Hub and monitors it with watchtower. Note the command argument changing the interval to 30s rather than the default 24 hours.</p>
applications (including <code>docker login</code> and <code>vim</code>) will not directly edit the file, but instead make a copy and replace
3 years ago