You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1 line
71 KiB
JSON
1 line
71 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"Watchtower <p> A container-based solution for automating Docker container base image updates. </p>"},{"location":"#quick_start","title":"Quick Start","text":"<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> docker rundocker-compose.yml <pre><code>$ docker run -d \\\n--name watchtower \\\n-v /var/run/docker.sock:/var/run/docker.sock \\\ncontainrrr/watchtower\n</code></pre> <pre><code>version: \"3\"\nservices:\n watchtower:\n image: containrrr/watchtower\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n</code></pre>"},{"location":"arguments/","title":"Arguments","text":"<p>By default, watchtower will monitor all containers running within the Docker daemon to which it is pointed (in most cases this will be the local Docker daemon, but you can override it with the <code>--host</code> option described in the next section). However, you can restrict watchtower to monitoring a subset of the running containers by specifying the container names as arguments when launching watchtower.</p> <pre><code>$ docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n containrrr/watchtower \\\n nginx redis\n</code></pre> <p>In the example above, watchtower will only monitor the containers named \"nginx\" and \"redis\" for updates -- all of the other running containers will be ignored. If you do not want watchtower to run as a daemon you can pass the <code>--run-once</code> flag and remove the watchtower container after its execution.</p> <pre><code>$ docker run --rm \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n containrrr/watchtower \\\n --run-once \\\n nginx redis\n</code></pre> <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>"},{"location":"arguments/#secretsfiles","title":"Secrets/Files","text":"<p>Some arguments can also reference a file, in which case the contents of the file are used as the value. This can be used to avoid putting secrets in the configuration file or command line.</p> <p>The following arguments are currently supported (including their corresponding <code>WATCHTOWER_</code> environment variables): - <code>notification-url</code> - <code>notification-email-server-password</code> - <code>notification-slack-hook-url</code> - <code>notification-msteams-hook</code> - <code>notification-gotify-token</code> - <code>http-api-token</code></p>"},{"location":"arguments/#example_docker-compose_usage","title":"Example docker-compose usage","text":"<pre><code>secrets:\n access_token:\n file: access_token\n\nservices:\n watchtower:\n secrets:\n - access_token\n environment:\n - WATCHTOWER_HTTP_API_TOKEN=/run/secrets/access_token\n</code></pre>"},{"location":"arguments/#help","title":"Help","text":"<p>Shows documentation about the supported flags.</p> <pre><code> Argument: --help\nEnvironment Variable: N/A\n Type: N/A\n Default: N/A\n</code></pre>"},{"location":"arguments/#time_zone","title":"Time Zone","text":"<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 this list, find your location and use the value in TZ Database Name, e.g Europe/Rome. The timezone can alternatively be set by volume mounting your hosts /etc/localtime file. <code>-v /etc/localtime:/etc/localtime:ro</code></p> <pre><code> Argument: N/A\nEnvironment Variable: TZ\n Type: String\n Default: \"UTC\"\n</code></pre>"},{"location":"arguments/#cleanup","title":"Cleanup","text":"<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> <pre><code> Argument: --cleanup\nEnvironment Variable: WATCHTOWER_CLEANUP\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#remove_anonymous_volumes","title":"Remove anonymous volumes","text":"<p>Removes anonymous volumes after updating. When this flag is specified, watchtower will remove all anonymous volumes from the container before restarting with a new image. Named volumes will not be removed!</p> <pre><code> Argument: --remove-volumes\nEnvironment Variable: WATCHTOWER_REMOVE_VOLUMES\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#debug","title":"Debug","text":"<p>Enable debug mode with verbose logging.</p> <p>Notes</p> <p>Alias for <code>--log-level debug</code>. See Maximum log level. Does not take an argument when used as an argument. Using <code>--debug true</code> will not work.</p> <pre><code> Argument: --debug, -d\nEnvironment Variable: WATCHTOWER_DEBUG\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#trace","title":"Trace","text":"<p>Enable trace mode with very verbose logging. Caution: exposes credentials!</p> <p>Notes</p> <p>Alias for <code>--log-level trace</code>. See Maximum log level. Does not take an argument when used as an argument. Using <code>--trace true</code> will not work.</p> <pre><code> Argument: --trace\nEnvironment Variable: WATCHTOWER_TRACE\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#maximum_log_level","title":"Maximum log level","text":"<p>The maximum log level that will be written to STDERR (shown in <code>docker log</code> when used in a container).</p> <pre><code> Argument: --log-level\nEnvironment Variable: WATCHTOWER_LOG_LEVEL\n Possible values: panic, fatal, error, warn, info, debug or trace\n Default: info\n</code></pre>"},{"location":"arguments/#logging_format","title":"Logging format","text":"<p>Sets what logging format to use for console output.</p> <pre><code> Argument: --log-format, -l\nEnvironment Variable: WATCHTOWER_LOG_FORMAT\n Possible values: Auto, LogFmt, Pretty or JSON\n Default: Auto\n</code></pre>"},{"location":"arguments/#ansi_colors","title":"ANSI colors","text":"<p>Disable ANSI color escape codes in log output.</p> <pre><code> Argument: --no-color\nEnvironment Variable: NO_COLOR\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#docker_host","title":"Docker host","text":"<p>Docker daemon socket to connect to. Can be pointed at a remote Docker host by specifying a TCP endpoint as \"tcp://hostname:port\".</p> <pre><code> Argument: --host, -H\nEnvironment Variable: DOCKER_HOST\n Type: String\n Default: \"unix:///var/run/docker.sock\"\n</code></pre>"},{"location":"arguments/#docker_api_version","title":"Docker API version","text":"<p>The API version to use by the Docker client for connecting to the Docker daemon. The minimum supported version is 1.24.</p> <pre><code> Argument: --api-version, -a\nEnvironment Variable: DOCKER_API_VERSION\n Type: String\n Default: \"1.24\"\n</code></pre>"},{"location":"arguments/#include_restarting","title":"Include restarting","text":"<p>Will also include restarting containers.</p> <pre><code> Argument: --include-restarting\nEnvironment Variable: WATCHTOWER_INCLUDE_RESTARTING\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#include_stopped","title":"Include stopped","text":"<p>Will also include created and exited containers.</p> <pre><code> Argument: --include-stopped, -S\nEnvironment Variable: WATCHTOWER_INCLUDE_STOPPED\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#revive_stopped","title":"Revive stopped","text":"<p>Start any stopped containers that have had their image updated. This argument is only usable with the <code>--include-stopped</code> argument.</p> <pre><code> Argument: --revive-stopped\nEnvironment Variable: WATCHTOWER_REVIVE_STOPPED\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#poll_interval","title":"Poll interval","text":"<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> <pre><code> Argument: --interval, -i\nEnvironment Variable: WATCHTOWER_POLL_INTERVAL\n Type: Integer\n Default: 86400 (24 hours)\n</code></pre>"},{"location":"arguments/#filter_by_enable_label","title":"Filter by enable label","text":"<p>Monitor and update containers that have a <code>com.centurylinklabs.watchtower.enable</code> label set to true.</p> <pre><code> Argument: --label-enable\nEnvironment Variable: WATCHTOWER_LABEL_ENABLE\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#filter_by_disable_label","title":"Filter by disable label","text":"<p>Do not Monitor and 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>"},{"location":"arguments/#filter_by_disabling_specific_container_names","title":"Filter by disabling specific container names","text":"<p>Monitor and update containers whose names are not in a given set of names.</p> <p>This can be used to exclude specific containers, when setting labels is not an option. The listed containers will be excluded even if they have the enable filter set to true.</p> <pre><code> Argument: --disable-containers, -x\nEnvironment Variable: WATCHTOWER_DISABLE_CONTAINERS\n Type: Comma- or space-separated string list\n Default: \"\"\n</code></pre>"},{"location":"arguments/#without_updating_containers","title":"Without updating containers","text":"<p>Will only monitor for new images, send notifications and invoke the pre-check/post-check hooks, but will not update the containers.</p> <p>Note</p> <p>Due to Docker API limitations the latest image will still be pulled from the registry. The HEAD digest checks allows watchtower to skip pulling when there are no changes, but to know what has changed it will still do a pull whenever the repository digest doesn't match the local image digest.</p> <pre><code> Argument: --monitor-only\nEnvironment Variable: WATCHTOWER_MONITOR_ONLY\n Type: Boolean\n Default: false\n</code></pre> <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>See With label taking precedence over arguments for behavior when both argument and label are set</p>"},{"location":"arguments/#with_label_taking_precedence_over_arguments","title":"With label taking precedence over arguments","text":"<p>By default, arguments will take precedence over labels. This means that if you set <code>WATCHTOWER_MONITOR_ONLY</code> to true or use <code>--monitor-only</code>, a container with <code>com.centurylinklabs.watchtower.monitor-only</code> set to false will not be updated. If you set <code>WATCHTOWER_LABEL_TAKE_PRECEDENCE</code> to true or use <code>--label-take-precedence</code>, then the container will also be updated. This also apply to the no pull option. if you set <code>WATCHTOWER_NO_PULL</code> to true or use <code>--no-pull</code>, a container with <code>com.centurylinklabs.watchtower.no-pull</code> set to false will not pull the new image. If you set <code>WATCHTOWER_LABEL_TAKE_PRECEDENCE</code> to true or use <code>--label-take-precedence</code>, then the container will pull image</p> <pre><code> Argument: --label-take-precedence\nEnvironment Variable: WATCHTOWER_LABEL_TAKE_PRECEDENCE\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#without_restarting_containers","title":"Without restarting containers","text":"<p>Do not restart containers after updating. This option can be useful when the start of the containers is managed by an external system such as systemd. <pre><code> Argument: --no-restart\nEnvironment Variable: WATCHTOWER_NO_RESTART\n Type: Boolean\n Default: false\n</code></pre></p>"},{"location":"arguments/#without_pulling_new_images","title":"Without pulling new images","text":"<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. Use this option if you are building new images directly on the Docker host without pushing them to a registry.</p> <pre><code> Argument: --no-pull\nEnvironment Variable: WATCHTOWER_NO_PULL\n Type: Boolean\n Default: false\n</code></pre> <p>Note that no-pull can also be specified on a per-container basis with the <code>com.centurylinklabs.watchtower.no-pull</code> label set on those containers.</p> <p>See With label taking precedence over arguments for behavior when both argument and label are set</p>"},{"location":"arguments/#without_sending_a_startup_message","title":"Without sending a startup message","text":"<p>Do not send a message after watchtower started. Otherwise there will be an info-level notification.</p> <pre><code> Argument: --no-startup-message\nEnvironment Variable: WATCHTOWER_NO_STARTUP_MESSAGE\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#run_once","title":"Run once","text":"<p>Run an update attempt against a container name list one time immediately and exit.</p> <pre><code> Argument: --run-once, -R\nEnvironment Variable: WATCHTOWER_RUN_ONCE\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#http_api_mode","title":"HTTP API Mode","text":"<p>Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. For details see HTTP API.</p> <pre><code> Argument: --http-api-update\nEnvironment Variable: WATCHTOWER_HTTP_API_UPDATE\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#http_api_token","title":"HTTP API Token","text":"<p>Sets an authentication token to HTTP API requests. Can also reference a file, in which case the contents of the file are used.</p> <pre><code> Argument: --http-api-token\nEnvironment Variable: WATCHTOWER_HTTP_API_TOKEN\n Type: String\n Default: -\n</code></pre>"},{"location":"arguments/#http_api_periodic_polls","title":"HTTP API periodic polls","text":"<p>Keep running periodic updates if the HTTP API mode is enabled, otherwise the HTTP API would prevent periodic polls. </p> <pre><code> Argument: --http-api-periodic-polls\nEnvironment Variable: WATCHTOWER_HTTP_API_PERIODIC_POLLS\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#filter_by_scope","title":"Filter by scope","text":"<p>Update containers that have a <code>com.centurylinklabs.watchtower.scope</code> label set with the same value as the given argument. This enables running multiple instances.</p> <p>Filter by lack of scope</p> <p>If you want other instances of watchtower to ignore the scoped containers, set this argument to <code>none</code>. When omitted, watchtower will update all containers regardless of scope.</p> <pre><code> Argument: --scope\nEnvironment Variable: WATCHTOWER_SCOPE\n Type: String\n Default: -\n</code></pre>"},{"location":"arguments/#http_api_metrics","title":"HTTP API Metrics","text":"<p>Enables a metrics endpoint, exposing prometheus metrics via HTTP. See Metrics for details. </p> <pre><code> Argument: --http-api-metrics\nEnvironment Variable: WATCHTOWER_HTTP_API_METRICS\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#scheduling","title":"Scheduling","text":"<p>Cron expression 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> <pre><code> Argument: --schedule, -s\nEnvironment Variable: WATCHTOWER_SCHEDULE\n Type: String\n Default: -\n</code></pre>"},{"location":"arguments/#rolling_restart","title":"Rolling restart","text":"<p>Restart one image at time instead of stopping and starting all at once. Useful in conjunction with lifecycle hooks to implement zero-downtime deploy.</p> <pre><code> Argument: --rolling-restart\nEnvironment Variable: WATCHTOWER_ROLLING_RESTART\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#wait_until_timeout","title":"Wait until timeout","text":"<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> <pre><code> Argument: --stop-timeout\nEnvironment Variable: WATCHTOWER_TIMEOUT\n Type: Duration\n Default: 10s\n</code></pre>"},{"location":"arguments/#tls_verification","title":"TLS Verification","text":"<p>Use TLS when connecting to the Docker socket and verify the server's certificate. See below for options used to configure notifications.</p> <pre><code> Argument: --tlsverify\nEnvironment Variable: DOCKER_TLS_VERIFY\n Type: Boolean\n Default: false\n</code></pre>"},{"location":"arguments/#head_failure_warnings","title":"HEAD failure warnings","text":"<p>When to warn about HEAD pull requests failing. Auto means that it will warn when the registry is known to handle the requests and may rate limit pull requests (mainly docker.io).</p> <pre><code> Argument: --warn-on-head-failure\nEnvironment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE\n Possible values: always, auto, never\n Default: auto\n</code></pre>"},{"location":"arguments/#health_check","title":"Health check","text":"<p>Returns a success exit code to enable usage with docker <code>HEALTHCHECK</code>. This check is naive and only returns checks whether there is another process running inside the container, as it is the only known form of failure state for watchtowers container.</p> <p>Only for HEALTHCHECK use</p> <p>Never put this on the main container executable command line as it is only meant to be run from docker HEALTHCHECK.</p> <pre><code> Argument: --health-check\n</code></pre>"},{"location":"arguments/#programatic_output_porcelain","title":"Programatic Output (porcelain)","text":"<p>Writes the session results to STDOUT using a stable, machine-readable format (indicated by the argument VERSION). </p> <p>Alias for:</p> <pre><code> --notification-url logger://\n --notification-log-stdout\n --notification-report\n --notification-template porcelain.VERSION.summary-no-log\n\n Argument: --porcelain, -P\nEnvironment Variable: WATCHTOWER_PORCELAIN\n Possible values: v1\n Default: -\n</code></pre>"},{"location":"container-selection/","title":"Container selection","text":"<p>By default, watchtower will watch all containers. However, sometimes only some containers should be updated.</p> <p>There are two options:</p> <ul> <li>Fully exclude: You can choose to exclude containers entirely from being watched by watchtower.</li> <li>Monitor only: In this mode, watchtower checks for container updates, sends notifications and invokes the pre-check/post-check hooks on the containers but does not perform the update.</li> </ul>"},{"location":"container-selection/#full_exclude","title":"Full Exclude","text":"<p>If you need to exclude some containers, set the com.centurylinklabs.watchtower.enable label to <code>false</code>. For clarity this should be set on the container(s) you wish to be ignored, this is not set on watchtower.</p> dockerfiledocker rundocker-compose <pre><code>LABEL com.centurylinklabs.watchtower.enable=\"false\"\n</code></pre> <pre><code>docker run -d --label=com.centurylinklabs.watchtower.enable=false someimage\n</code></pre> <pre><code>version: \"3\"\nservices:\n someimage:\n container_name: someimage\n labels:\n - \"com.centurylinklabs.watchtower.enable=false\"\n</code></pre> <p>If instead you want to only include containers with the enable label, pass the <code>--label-enable</code> flag or the <code>WATCHTOWER_LABEL_ENABLE</code> environment variable on startup for watchtower and set the com.centurylinklabs.watchtower.enable label with a value of <code>true</code> on the containers you want to watch.</p> dockerfiledocker rundocker-compose <pre><code>LABEL com.centurylinklabs.watchtower.enable=\"true\"\n</code></pre> <pre><code>docker run -d --label=com.centurylinklabs.watchtower.enable=true someimage\n</code></pre> <pre><code>version: \"3\"\nservices:\n someimage:\n container_name: someimage\n labels:\n - \"com.centurylinklabs.watchtower.enable=true\"\n</code></pre> <p>If you wish to create a monitoring scope, you will need to run multiple instances and set a scope for each of them.</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> <ul> <li>If a container's name is on the monitoring name list (not empty <code>--name</code> argument) but it is not enabled (centurylinklabs.watchtower.enable=false), it won't be monitored;</li> <li>If a container's name is not on the monitoring name list (not empty <code>--name</code> argument), even if it is enabled (centurylinklabs.watchtower.enable=true and <code>--label-enable</code> flag is set), it won't be monitored;</li> </ul>"},{"location":"container-selection/#monitor_only","title":"Monitor Only","text":"<p>Individual containers can be marked to only be monitored (without being updated).</p> <p>To do so, set the com.centurylinklabs.watchtower.monitor-only label to <code>true</code> on that container.</p> <pre><code>LABEL com.centurylinklabs.watchtower.monitor-only=\"true\"\n</code></pre> <p>Or, it can be specified as part of the <code>docker run</code> command line:</p> <pre><code>docker run -d --label=com.centurylinklabs.watchtower.monitor-only=true someimage\n</code></pre> <p>When the label is specified on a container, watchtower treats that container exactly as if <code>WATCHTOWER_MONITOR_ONLY</code> was set, but the effect is limited to the individual container. </p>"},{"location":"http-api-mode/","title":"HTTP API Mode","text":"<p>Watchtower provides an HTTP API mode that enables an HTTP endpoint that can be requested to trigger container updating. The current available endpoint list is:</p> <ul> <li><code>/v1/update</code> - triggers an update for all of the containers monitored by this Watchtower instance.</li> </ul> <p>To enable this mode, use the flag <code>--http-api-update</code>. For example, in a Docker Compose config file:</p> <pre><code>version: '3'\n\nservices:\n app-monitored-by-watchtower:\n image: myapps/monitored-by-watchtower\n labels:\n - \"com.centurylinklabs.watchtower.enable=true\"\n\n watchtower:\n image: containrrr/watchtower\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n command: --debug --http-api-update\n environment:\n - WATCHTOWER_HTTP_API_TOKEN=mytoken\n labels:\n - \"com.centurylinklabs.watchtower.enable=false\"\n ports:\n - 8080:8080\n</code></pre> <p>By default, enabling this mode prevents periodic polls (i.e. what is specified using <code>--interval</code> or <code>--schedule</code>). To run periodic updates regardless, pass <code>--http-api-periodic-polls</code>.</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> <pre><code>curl -H \"Authorization: Bearer mytoken\" localhost:8080/v1/update\n</code></pre>"},{"location":"introduction/","title":"Introduction","text":"<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>For example, let's say you were running watchtower along with an instance of centurylink/wetty-cli image:</p> <pre><code>$ docker ps\nCONTAINER ID IMAGE STATUS PORTS NAMES\n967848166a45 centurylink/wetty-cli Up 10 minutes 0.0.0.0:8080->3000/tcp wetty\n6cc4d2a9d1a5 containrrr/watchtower Up 15 minutes watchtower\n</code></pre> <p>Every day watchtower will pull the latest centurylink/wetty-cli 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>"},{"location":"lifecycle-hooks/","title":"Lifecycle hooks","text":""},{"location":"lifecycle-hooks/#executing_commands_before_and_after_updating","title":"Executing commands before and after updating","text":"<p>Note</p> <p>These are shell commands executed with <code>sh</code>, and therefore require the container to provide the <code>sh</code> executable.</p> <p>DO NOTE: If the container is not running then lifecycle hooks can not run and therefore the update is executed without running any lifecycle hooks.</p> <p>It is possible to execute pre/post-check and pre/post-update commands inside every container updated by watchtower.</p> <ul> <li>The pre-check command is executed for each container prior to every update cycle.</li> <li>The pre-update command is executed before stopping the container when an update is about to start.</li> <li>The post-update command is executed after restarting the updated container</li> <li>The post-check command is executed for each container post every update cycle.</li> </ul> <p>This feature is disabled by default. To enable it, you need to set the option <code>--enable-lifecycle-hooks</code> on the command line, or set the environment variable <code>WATCHTOWER_LIFECYCLE_HOOKS</code> to <code>true</code>.</p>"},{"location":"lifecycle-hooks/#specifying_update_commands","title":"Specifying update commands","text":"<p>The commands are specified using docker container labels, the following are currently available:</p> Type Docker Container Label Pre Check <code>com.centurylinklabs.watchtower.lifecycle.pre-check</code> Pre Update <code>com.centurylinklabs.watchtower.lifecycle.pre-update</code> Post Update <code>com.centurylinklabs.watchtower.lifecycle.post-update</code> Post Check <code>com.centurylinklabs.watchtower.lifecycle.post-check</code> <p>These labels can be declared as instructions in a Dockerfile (with some example .sh files) or be specified as part of the <code>docker run</code> command line:</p> Dockerfiledocker run <pre><code>LABEL com.centurylinklabs.watchtower.lifecycle.pre-check=\"/sync.sh\"\nLABEL com.centurylinklabs.watchtower.lifecycle.pre-update=\"/dump-data.sh\"\nLABEL com.centurylinklabs.watchtower.lifecycle.post-update=\"/restore-data.sh\"\nLABEL com.centurylinklabs.watchtower.lifecycle.post-check=\"/send-heartbeat.sh\"\n</code></pre> <pre><code>docker run -d \\\n--label=com.centurylinklabs.watchtower.lifecycle.pre-check=\"/sync.sh\" \\\n--label=com.centurylinklabs.watchtower.lifecycle.pre-update=\"/dump-data.sh\" \\\n--label=com.centurylinklabs.watchtower.lifecycle.post-update=\"/restore-data.sh\" \\\nsomeimage --label=com.centurylinklabs.watchtower.lifecycle.post-check=\"/send-heartbeat.sh\" \\\n</code></pre>"},{"location":"lifecycle-hooks/#timeouts","title":"Timeouts","text":"<p>The timeout for all lifecycle commands is 60 seconds. After that, a timeout will occur, forcing Watchtower to continue the update loop.</p>"},{"location":"lifecycle-hooks/#pre-_or_post-update_timeouts","title":"Pre- or Post-update timeouts","text":"<p>For the <code>pre-update</code> or <code>post-update</code> lifecycle command, it is possible to override this timeout to allow the script to finish before forcefully killing it. This is done by adding the label <code>com.centurylinklabs.watchtower.lifecycle.pre-update-timeout</code> or post-update-timeout respectively followed by the timeout expressed in minutes.</p> <p>If the label value is explicitly set to <code>0</code>, the timeout will be disabled. </p>"},{"location":"lifecycle-hooks/#execution_failure","title":"Execution failure","text":"<p>The failure of a command to execute, identified by an exit code different than 0 or 75 (EX_TEMPFAIL), will not prevent watchtower from updating the container. Only an error log statement containing the exit code will be reported.</p>"},{"location":"linked-containers/","title":"Linked containers","text":"<p>Watchtower will detect if there are links between any of the running containers and ensures that things are stopped/started in a way that won't break any of the links. If an update is detected for one of the dependencies in a group of linked containers, watchtower will stop and start all of the containers in the correct order so that the application comes back up correctly.</p> <p>For example, imagine you were running a mysql container and a wordpress container which had been linked to the mysql container. If watchtower were to detect that the mysql container required an update, it would first shut down the linked wordpress container followed by the mysql container. When restarting the containers it would handle mysql first and then wordpress to ensure that the link continued to work.</p> <p>If you want to override existing links, or if you are not using links, you can use special <code>com.centurylinklabs.watchtower.depends-on</code> label with dependent container names, separated by a comma.</p> <p>When you have a depending container that is using <code>network_mode: service:container</code> then watchtower will treat that container as an implicit link.</p>"},{"location":"metrics/","title":"Metrics","text":"<p>Experimental feature</p> <p>This feature was added in v1.0.4 and is still considered experimental. If you notice any strange behavior, please raise a ticket in the repository issues.</p> <p>Metrics can be used to track how Watchtower behaves over time.</p> <p>To use this feature, you have to set an API token and enable the metrics API, as well as creating a port mapping for your container for port <code>8080</code>.</p> <p>The metrics API endpoint is <code>/v1/metrics</code>.</p>"},{"location":"metrics/#available_metrics","title":"Available Metrics","text":"Name Type Description <code>watchtower_containers_scanned</code> Gauge Number of containers scanned for changes by watchtower during the last scan <code>watchtower_containers_updated</code> Gauge Number of containers updated by watchtower during the last scan <code>watchtower_containers_failed</code> Gauge Number of containers where update failed during the last scan <code>watchtower_scans_total</code> Counter Number of scans since the watchtower started <code>watchtower_scans_skipped</code> Counter Number of skipped scans since watchtower started"},{"location":"metrics/#example_prometheus_scrape_config","title":"Example Prometheus <code>scrape_config</code>","text":"<pre><code>scrape_configs:\n - job_name: watchtower\n scrape_interval: 5s\n metrics_path: /v1/metrics\n bearer_token: demotoken\n static_configs:\n - targets:\n - 'watchtower:8080'\n</code></pre> <p>Replace <code>demotoken</code> with the Bearer token you have set accordingly.</p>"},{"location":"metrics/#demo","title":"Demo","text":"<p>The repository contains a demo with prometheus and grafana, available through <code>docker-compose.yml</code>. This demo is preconfigured with a dashboard, which will look something like this:</p> <p></p>"},{"location":"notifications/","title":"Notifications","text":"<p>Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging system, logrus. </p> <p>Using multiple notifications with environment variables</p> <p>There is currently a bug in Viper (spf13/viper#380), 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: <pre><code>WATCHTOWER_NOTIFICATIONS=\"slack msteams\"\n</code></pre> 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>). This prevents unexpected errors when watchtower starts.</p>"},{"location":"notifications/#settings","title":"Settings","text":"<ul> <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-hostname</code> (env. <code>WATCHTOWER_NOTIFICATIONS_HOSTNAME</code>): Custom hostname specified in subject/title. Useful to override the operating system hostname.</li> <li><code>--notifications-delay</code> (env. <code>WATCHTOWER_NOTIFICATIONS_DELAY</code>): Delay before sending notifications expressed in seconds.</li> <li>Watchtower will post a notification every time it is started. This behavior can be changed with an argument.</li> <li><code>--notification-title-tag</code> (env. <code>WATCHTOWER_NOTIFICATION_TITLE_TAG</code>): Prefix to include in the title. Useful when running multiple watchtowers.</li> <li><code>--notification-skip-title</code> (env. <code>WATCHTOWER_NOTIFICATION_SKIP_TITLE</code>): Do not pass the title param to notifications. This will not pass a dynamic title override to notification services. If no title is configured for the service, it will remove the title all together.</li> <li><code>--notification-log-stdout</code> (env. <code>WATCHTOWER_NOTIFICATION_LOG_STDOUT</code>): Enable output from <code>logger://</code> shoutrrr service to stdout.</li> </ul>"},{"location":"notifications/#shoutrrr_notifications","title":"shoutrrr notifications","text":"<p>To send notifications via shoutrrr, the following command-line options, or their corresponding environment variables, can be set:</p> <ul> <li><code>--notification-url</code> (env. <code>WATCHTOWER_NOTIFICATION_URL</code>): The shoutrrr service URL to be used. This option can also reference a file, in which case the contents of the file are used.</li> </ul> <p>Go to containrrr.dev/shoutrrr/v0.8/services/overview to 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> <ul> <li><code>--notification-template</code> (env. <code>WATCHTOWER_NOTIFICATION_TEMPLATE</code>): The template used for the message.</li> </ul> <p>The template is a Go template that either format a list of log entries or a <code>notification.Data</code> struct.</p> <p>Simple templates are used unless the <code>notification-report</code> flag is specified:</p> <ul> <li><code>--notification-report</code> (env. <code>WATCHTOWER_NOTIFICATION_REPORT</code>): Use the session report as the notification template data.</li> </ul>"},{"location":"notifications/#simple_templates","title":"Simple templates","text":"<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> <p>Custom date format</p> <p>If you want to adjust the date/time format it must show how the reference time (Mon Jan 2 15:04:05 MST 2006) would be displayed in your custom format. 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> <p>Example:</p> <pre><code>docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n -e WATCHTOWER_NOTIFICATION_URL=\"discord://token@channel slack://watchtower@token-a/token-b/token-c\" \\\n -e WATCHTOWER_NOTIFICATION_TEMPLATE=\"{{range .}}{{.Time.Format \\\"2006-01-02 15:04:05\\\"}} ({{.Level}}): {{.Message}}{{println}}{{end}}\" \\\n containrrr/watchtower\n</code></pre>"},{"location":"notifications/#report_templates","title":"Report templates","text":"<p>The default template for report notifications are the following: <pre><code>{{- if .Report -}}\n {{- with .Report -}}\n {{- if ( or .Updated .Failed ) -}}\n{{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Failed}} Failed\n {{- range .Updated}}\n- {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}}\n {{- end -}}\n {{- range .Fresh}}\n- {{.Name}} ({{.ImageName}}): {{.State}}\n {{- end -}}\n {{- range .Skipped}}\n- {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}\n {{- end -}}\n {{- range .Failed}}\n- {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}\n {{- end -}}\n {{- end -}}\n {{- end -}}\n{{- else -}}\n {{range .Entries -}}{{.Message}}{{\"\\n\"}}{{- end -}}\n{{- end -}}\n</code></pre></p> <p>It will be used to send a summary of every session if there are any containers that were updated or which failed to update.</p> <p>Skipping notifications</p> <p>Whenever the result of applying the template results in an empty string, no notifications will be sent. This is by default used to limit the notifications to only be sent when there something noteworthy occurred.</p> <p>You can replace <code>{{- if ( or .Updated .Failed ) -}}</code> with any logic you want to decide when to send the notifications.</p> <p>Example using a custom report template that always sends a session report after each run:</p> docker rundocker-compose <pre><code>docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n -e WATCHTOWER_NOTIFICATION_REPORT=\"true\" \\\n -e WATCHTOWER_NOTIFICATION_URL=\"discord://token@channel slack://watchtower@token-a/token-b/token-c\" \\\n -e WATCHTOWER_NOTIFICATION_TEMPLATE=\"\n {{- if .Report -}}\n {{- with .Report -}}\n {{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Failed}} Failed\n {{- range .Updated}}\n - {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}}\n {{- end -}}\n {{- range .Fresh}}\n - {{.Name}} ({{.ImageName}}): {{.State}}\n {{- end -}}\n {{- range .Skipped}}\n - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}\n {{- end -}}\n {{- range .Failed}}\n - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}\n {{- end -}}\n {{- end -}}\n {{- else -}}\n {{range .Entries -}}{{.Message}}{{\\\"\\n\\\"}}{{- end -}}\n {{- end -}}\n \" \\\n containrrr/watchtower\n</code></pre> <pre><code>version: \"3\"\nservices:\n watchtower:\n image: containrrr/watchtower\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n env:\n WATCHTOWER_NOTIFICATION_REPORT: \"true\"\n WATCHTOWER_NOTIFICATION_URL: >\n discord://token@channel\n slack://watchtower@token-a/token-b/token-c\n WATCHTOWER_NOTIFICATION_TEMPLATE: |\n {{- if .Report -}}\n {{- with .Report -}}\n {{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Failed}} Failed\n {{- range .Updated}}\n - {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}}\n {{- end -}}\n {{- range .Fresh}}\n - {{.Name}} ({{.ImageName}}): {{.State}}\n {{- end -}}\n {{- range .Skipped}}\n - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}\n {{- end -}}\n {{- range .Failed}}\n - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}}\n {{- end -}}\n {{- end -}}\n {{- else -}}\n {{range .Entries -}}{{.Message}}{{\"\\n\"}}{{- end -}}\n {{- end -}}\n</code></pre>"},{"location":"notifications/#legacy_notifications","title":"Legacy notifications","text":"<p>For backwards compatibility, the notifications can also be configured using legacy notification options. These will automatically be converted to shoutrrr URLs when used. 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> <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>msteams</code> to send notifications via MSTeams webhook</li> <li><code>gotify</code> to send notifications via Gotify</li> </ul>"},{"location":"notifications/#notify-upgrade","title":"<code>notify-upgrade</code>","text":"<p>If watchtower is started with <code>notify-upgrade</code> as it's first argument, it will generate a .env file with your current legacy notification options converted to shoutrrr URLs.</p> docker rundocker-compose.yml <pre><code>$ docker run -d \\\n--name watchtower \\\n-v /var/run/docker.sock:/var/run/docker.sock \\\n-e WATCHTOWER_NOTIFICATIONS=slack \\\n-e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=\"https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy\" \\\ncontainrrr/watchtower \\\nnotify-upgrade\n</code></pre> <pre><code>version: \"3\"\nservices:\n watchtower:\n image: containrrr/watchtower\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n env:\n WATCHTOWER_NOTIFICATIONS: slack\n WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy\n command: notify-upgrade\n</code></pre> <p>You can then copy this file from the container (a message with the full command to do so will be logged) and use it with your current setup:</p> docker rundocker-compose.yml <pre><code>$ docker run -d \\\n--name watchtower \\\n-v /var/run/docker.sock:/var/run/docker.sock \\\n--env-file watchtower-notifications.env \\\ncontainrrr/watchtower\n</code></pre> <pre><code>version: \"3\"\nservices:\n watchtower:\n image: containrrr/watchtower\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n env_file:\n - watchtower-notifications.env\n</code></pre>"},{"location":"notifications/#email","title":"Email","text":"<p>To receive notifications by email, the following command-line options, or their corresponding environment variables, can be set:</p> <ul> <li><code>--notification-email-from</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_FROM</code>): The e-mail address from which notifications will be sent.</li> <li><code>--notification-email-to</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_TO</code>): The e-mail address to which notifications will be sent.</li> <li><code>--notification-email-server</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_SERVER</code>): The SMTP server to send e-mails through.</li> <li><code>--notification-email-server-tls-skip-verify</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY</code>): Do not verify the TLS certificate of the mail server. This should be used only for testing.</li> <li><code>--notification-email-server-port</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT</code>): The port used to connect to the SMTP server to send e-mails through. Defaults to <code>25</code>.</li> <li><code>--notification-email-server-user</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER</code>): The username to authenticate with the SMTP server with.</li> <li><code>--notification-email-server-password</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD</code>): The password to authenticate with the SMTP server with. Can also reference a file, in which case the contents of the file are used.</li> <li><code>--notification-email-delay</code> (env. <code>WATCHTOWER_NOTIFICATION_EMAIL_DELAY</code>): Delay before sending notifications expressed in seconds.</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. NOTE: This will affect all notification types.</li> </ul> <p>Example:</p> <pre><code>docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n -e WATCHTOWER_NOTIFICATIONS=email \\\n -e WATCHTOWER_NOTIFICATION_EMAIL_FROM=fromaddress@gmail.com \\\n -e WATCHTOWER_NOTIFICATION_EMAIL_TO=toaddress@gmail.com \\\n -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \\\n -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \\\n -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=fromaddress@gmail.com \\\n -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=app_password \\\n -e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=2 \\\n containrrr/watchtower\n</code></pre> <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 freinet/postfix-relay.</p> <p>Example including an SMTP relay:</p> <pre><code>version: '3.8'\nservices:\n watchtower:\n image: containrrr/watchtower:latest\n container_name: watchtower\n environment:\n WATCHTOWER_MONITOR_ONLY: 'true'\n WATCHTOWER_NOTIFICATIONS: email\n WATCHTOWER_NOTIFICATION_EMAIL_FROM: from-address@your-domain.com\n WATCHTOWER_NOTIFICATION_EMAIL_TO: to-address@your-domain.com\n # you have to use a network alias here, if you use your own certificate\n WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.your-domain.com\n WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 25\n WATCHTOWER_NOTIFICATION_EMAIL_DELAY: 2\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n networks:\n - watchtower\n depends_on:\n - postfix\n\n # SMTP needed to send out status emails\n postfix:\n image: freinet/postfix-relay:latest\n expose:\n - 25\n environment:\n MAILNAME: somename.your-domain.com\n TLS_KEY: '/etc/ssl/domains/your-domain.com/your-domain.com.key'\n TLS_CRT: '/etc/ssl/domains/your-domain.com/your-domain.com.crt'\n TLS_CA: '/etc/ssl/domains/your-domain.com/intermediate.crt'\n volumes:\n - /etc/ssl/domains/your-domain.com/:/etc/ssl/domains/your-domain.com/:ro\n networks:\n watchtower:\n # this alias is really important to make your certificate work\n aliases:\n - smtp.your-domain.com\nnetworks:\n watchtower:\n external: false\n</code></pre>"},{"location":"notifications/#slack","title":"Slack","text":"<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>Additionally, you should set the Slack webhook URL using the <code>--notification-slack-hook-url</code> option or the <code>WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL</code> environment variable. This option can also reference a file, in which case the contents of the file are used.</p> <p>By default, watchtower will send messages under the name <code>watchtower</code>, you can customize this string through the <code>--notification-slack-identifier</code> option or the <code>WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER</code> environment variable.</p> <p>Other, optional, variables include:</p> <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> </ul> <p>Example:</p> <pre><code>docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n -e WATCHTOWER_NOTIFICATIONS=slack \\\n -e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=\"https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy\" \\\n -e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server-1 \\\n -e WATCHTOWER_NOTIFICATION_SLACK_CHANNEL=#my-custom-channel \\\n containrrr/watchtower\n</code></pre>"},{"location":"notifications/#microsoft_teams","title":"Microsoft Teams","text":"<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>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> <pre><code>docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n -e WATCHTOWER_NOTIFICATIONS=msteams \\\n -e WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL=\"https://outlook.office.com/webhook/xxxxxxxx@xxxxxxx/IncomingWebhook/yyyyyyyy/zzzzzzzzzz\" \\\n -e WATCHTOWER_NOTIFICATION_MSTEAMS_USE_LOG_DATA=true \\\n containrrr/watchtower\n</code></pre>"},{"location":"notifications/#gotify","title":"Gotify","text":"<p>To push a notification to your Gotify instance, register a Gotify app and specify the Gotify URL and app token:</p> <pre><code>docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n -e WATCHTOWER_NOTIFICATIONS=gotify \\\n -e WATCHTOWER_NOTIFICATION_GOTIFY_URL=\"https://my.gotify.tld/\" \\\n -e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN=\"SuperSecretToken\" \\\n containrrr/watchtower\n</code></pre> <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>"},{"location":"private-registries/","title":"Private registries","text":"<p>Watchtower supports private Docker image registries. In many cases, accessing a private registry requires a valid username and password (i.e., credentials). In order to operate in such an environment, watchtower needs to know the credentials to access the registry. </p> <p>The credentials can be provided to watchtower in a configuration file called <code>config.json</code>. There are two ways to generate this configuration file:</p> <ul> <li>The configuration file can be created manually.</li> <li>Call <code>docker login <REGISTRY_NAME></code> and share the resulting configuration file.</li> </ul>"},{"location":"private-registries/#create_the_configuration_file_manually","title":"Create the configuration file manually","text":"<p>Create a new configuration file with the following syntax and a base64 encoded username and password <code>auth</code> string:</p> <pre><code>{\n \"auths\": {\n \"<REGISTRY_NAME>\": {\n \"auth\": \"XXXXXXX\"\n }\n }\n}\n</code></pre> <p><code><REGISTRY_NAME></code> needs to be replaced by the name of your private registry (e.g., <code>my-private-registry.example.org</code>).</p> <p>Using private images on Docker Hub</p> <p>To access private repositories on Docker Hub, <code><REGISTRY_NAME></code> should be <code>https://index.docker.io/v1/</code>. In this special case, the registry domain does not have to be specified in <code>docker run</code> or <code>docker-compose</code>. Like Docker, Watchtower will use the Docker Hub registry and its credentials when no registry domain is specified.</p> <p><sub>Watchtower will recognize credentials with <code><REGISTRY_NAME></code> <code>index.docker.io</code>, but the Docker CLI will not.</sub></p> <p>Using a private registry on a local host</p> <p>To use a private registry hosted locally, make sure to correctly specify the registry host in both <code>config.json</code> and the <code>docker run</code> command or <code>docker-compose</code> file. Valid hosts are <code>localhost[:PORT]</code>, <code>HOST:PORT</code>, or any multi-part <code>domain.name</code> or IP-address with or without a port.</p> <p>Examples: * <code>localhost</code> -> <code>localhost/myimage</code> * <code>127.0.0.1</code> -> <code>127.0.0.1/myimage:mytag</code> * <code>host.domain</code> -> <code>host.domain/myorganization/myimage</code> * <code>other-lan-host:80</code> -> <code>other-lan-host:80/imagename:latest</code></p> <p>The required <code>auth</code> string can be generated as follows:</p> <pre><code>echo -n 'username:password' | base64\n</code></pre> <p>Username and Password for GCloud</p> <p>For gcloud, we'll use <code>_json_key</code> as our username and the content of <code>gcloudauth.json</code> as the password. <pre><code>bash echo -n \"_json_key:$(cat gcloudauth.json)\" | base64 -w0\n</code></pre></p> <p>When the watchtower Docker container is started, the created configuration file (<code><PATH>/config.json</code> in this example) needs to be passed to the container:</p> <pre><code>docker run [...] -v <PATH>/config.json:/config.json containrrr/watchtower\n</code></pre>"},{"location":"private-registries/#share_the_docker_configuration_file","title":"Share the Docker configuration file","text":"<p>To pull an image from a private registry, <code>docker login</code> needs to be called first, to get access to the registry. The provided credentials are stored in a configuration file called <code><PATH_TO_HOME_DIR>/.docker/config.json</code>. This configuration file can be directly used by watchtower. In this case, the creation of an additional configuration file is not necessary.</p> <p>When the Docker container is started, pass the configuration file to watchtower:</p> <pre><code>docker run [...] -v <PATH_TO_HOME_DIR>/.docker/config.json:/config.json containrrr/watchtower\n</code></pre> <p>When creating the watchtower container via docker-compose, use the following lines:</p> <pre><code>version: \"3.4\"\nservices:\n watchtower:\n image: containrrr/watchtower:latest\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n - <PATH_TO_HOME_DIR>/.docker/config.json:/config.json\n ...\n</code></pre>"},{"location":"private-registries/#docker_config_path","title":"Docker Config path","text":"<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. Example usage:</p> <pre><code>version: \"3.4\"\n\nservices: \n watchtower:\n image: containrrr/watchtower\n environment:\n DOCKER_CONFIG: /config\n volumes:\n - /etc/watchtower/config/:/config/\n - /var/run/docker.sock:/var/run/docker.sock\n</code></pre>"},{"location":"private-registries/#credential_helpers","title":"Credential helpers","text":"<p>Some private Docker registries (the most prominent probably being AWS ECR) use non-standard ways of authentication. To be able to use this together with watchtower, we need to use a credential helper.</p> <p>To keep the image size small we've decided to not include any helpers in the watchtower image, instead we'll put the helper in a separate container and mount it using volumes.</p>"},{"location":"private-registries/#example","title":"Example","text":"<p>Example implementation for use with amazon-ecr-credential-helper:</p> <p>Use the dockerfile below to build the amazon-ecr-credential-helper, in a volume that may be mounted onto your watchtower container.</p> <ol> <li> <p>Create the Dockerfile (contents below): <pre><code>FROM golang:1.17\n\nENV GO111MODULE off\nENV CGO_ENABLED 0\nENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login\n\nRUN go get -u $REPO\n\nRUN rm /go/bin/docker-credential-ecr-login\n\nRUN go build \\\n -o /go/bin/docker-credential-ecr-login \\\n /go/src/$REPO\n\nWORKDIR /go/bin/\n</code></pre></p> </li> <li> <p>Use the following commands to build the aws-ecr-dock-cred-helper and store it's output in a volume: <pre><code># Create a volume to store the command (once built)\ndocker volume create helper \n\n# Build the container\ndocker build -t aws-ecr-dock-cred-helper .\n\n# Build the command and store it in the new volume in the /go/bin directory.\ndocker run -d --rm --name aws-cred-helper \\\n --volume helper:/go/bin aws-ecr-dock-cred-helper\n</code></pre></p> </li> <li> <p>Create a configuration file for docker, and store it in $HOME/.docker/config.json (replace the placeholders with your AWS Account ID and with your AWS ECR Region): <pre><code>{\n \"credsStore\" : \"ecr-login\",\n \"HttpHeaders\" : {\n \"User-Agent\" : \"Docker-Client/19.03.1 (XXXXXX)\"\n },\n \"auths\" : {\n \"<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_ECR_REGION>.amazonaws.com\" : {}\n },\n \"credHelpers\": {\n \"<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_ECR_REGION>.amazonaws.com\" : \"ecr-login\"\n }\n}\n</code></pre> <li> <p>Create a docker-compose file (as an example) to help launch the container: <pre><code>version: \"3.4\"\nservices:\n # Check for new images and restart things if a new image exists\n # for any of our containers.\n watchtower:\n image: containrrr/watchtower:latest\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n - .docker/config.json:/config.json\n - helper:/go/bin\n environment:\n - HOME=/\n - PATH=$PATH:/go/bin\n - AWS_REGION=us-west-1\nvolumes:\n helper: \n external: true\n</code></pre></p> </li> <p>A few additional notes:</p> <ol> <li> <p>With docker-compose the volume (helper, in this case) MUST be set to <code>external: true</code>, otherwise docker-compose will preface it with the directory name.</p> </li> <li> <p>Note that \"credsStore\" : \"ecr-login\" is needed - and in theory if you have that you can remove the credHelpers section</p> </li> <li> <p>I have this running on an EC2 instance that has credentials assigned to it - so no keys are needed; however, you may need to include the <code>AWS_ACCESS_KEY_ID</code> and <code>AWS_SECRET_ACCESS_KEY</code> environment variables as well.</p> </li> <li> <p>An alternative to adding the various variables is to create a ~/.aws/config and ~/.aws/credentials files and place the settings there, then mount the ~/.aws directory to / in the container.</p> </li> </ol>"},{"location":"remote-hosts/","title":"Remote hosts","text":"<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> <pre><code>docker run -d \\\n --name watchtower \\\n containrrr/watchtower --host \"tcp://10.0.1.2:2375\"\n</code></pre> <p>or</p> <pre><code>docker run -d \\\n --name watchtower \\\n -e DOCKER_HOST=\"tcp://10.0.1.2:2375\" \\\n containrrr/watchtower\n</code></pre> <p>Note in both of the examples above that it is unnecessary to mount the /var/run/docker.sock into the watchtower container.</p>"},{"location":"running-multiple-instances/","title":"Running multiple instances","text":"<p>By default, Watchtower will clean up other instances and won't allow multiple instances running on the same Docker host or swarm. It is possible to override this behavior by defining a scope to each running instance. </p> <p>Note</p> <ul> <li>Multiple instances can't run with the same scope;</li> <li>An instance without a scope will clean up other running instances, even if they have a defined scope;</li> <li>Supplying <code>none</code> as the scope will treat <code>com.centurylinklabs.watchtower.scope=none</code>, <code>com.centurylinklabs.watchtower.scope=</code> and the lack of a <code>com.centurylinklabs.watchtower.scope</code> label as the scope <code>none</code>. This effectly enables you to run both scoped and unscoped watchtower instances on the same machine.</li> </ul> <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 <code>com.centurylinklabs.watchtower.scope</code> 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> <pre><code>version: '3'\n\nservices:\n app-with-scope:\n image: myapps/monitored-by-watchtower\n labels: [ \"com.centurylinklabs.watchtower.scope=myscope\" ]\n\n scoped-watchtower:\n image: containrrr/watchtower\n volumes: [ \"/var/run/docker.sock:/var/run/docker.sock\" ]\n command: --interval 30 --scope myscope\n labels: [ \"com.centurylinklabs.watchtower.scope=myscope\" ] \n\n unscoped-app-a:\n image: myapps/app-a\n\n unscoped-app-b:\n image: myapps/app-b\n labels: [ \"com.centurylinklabs.watchtower.scope=none\" ]\n\n unscoped-app-c:\n image: myapps/app-b\n labels: [ \"com.centurylinklabs.watchtower.scope=\" ]\n\n unscoped-watchtower:\n image: containrrr/watchtower\n volumes: [ \"/var/run/docker.sock:/var/run/docker.sock\" ]\n command: --interval 30 --scope none\n</code></pre>"},{"location":"secure-connections/","title":"Secure connections","text":"<p>Watchtower is also capable of connecting to Docker endpoints which are protected by SSL/TLS. If you've used docker-machine to provision your remote Docker host, you simply need to volume mount the certificates generated by docker-machine into the watchtower container and optionally specify <code>--tlsverify</code> flag.</p> <p>The docker-machine 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 /etc/ssl/docker.</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> <pre><code>docker run -d \\\n --name watchtower \\\n -e DOCKER_HOST=$DOCKER_HOST \\\n -e DOCKER_CERT_PATH=/etc/ssl/docker \\\n -v $DOCKER_CERT_PATH:/etc/ssl/docker \\\n containrrr/watchtower --tlsverify\n</code></pre>"},{"location":"stop-signals/","title":"Stop signals","text":"<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 com.centurylinklabs.watchtower.stop-signal 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> <pre><code>LABEL com.centurylinklabs.watchtower.stop-signal=\"SIGHUP\"\n</code></pre> <p>Or, it can be specified as part of the <code>docker run</code> command line:</p> <pre><code>docker run -d --label=com.centurylinklabs.watchtower.stop-signal=SIGHUP someimage\n</code></pre>"},{"location":"template-preview/","title":"Template preview","text":"<pre>loading wasm...</pre> {{- with .Report -}} {{- if ( or .Updated .Failed ) -}} {{len .Scanned}} Scanned, {{len .Updated}} Updated, {{len .Failed}} Failed {{- range .Updated}} - {{.Name}} ({{.ImageName}}): {{.CurrentImageID.ShortID}} updated to {{.LatestImageID.ShortID}} {{- end -}} {{- range .Fresh}} - {{.Name}} ({{.ImageName}}): {{.State}} {{- end -}} {{- range .Skipped}} - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}} {{- end -}} {{- range .Failed}} - {{.Name}} ({{.ImageName}}): {{.State}}: {{.Error}} {{- end -}} {{- end -}} {{- end -}} {{- if (and .Entries .Report) }} Logs: {{ end -}} {{range .Entries -}}{{.Time.Format \"2006-01-02T15:04:05Z07:00\"}} [{{.Level}}] {{.Message}}{{\"\\n\"}}{{- end -}} Container report Skipped: Scanned: Updated: Failed: Fresh: Stale: Log entries Error: Warning: Info: Debug: Update preview <pre></pre>"},{"location":"updating/","title":"Updating","text":""},{"location":"updating/#updating_watchtower","title":"Updating Watchtower","text":"<p>If watchtower is monitoring the same Docker daemon under which the watchtower container itself is running (i.e. if you volume-mounted <code>/var/run/docker.sock</code> into the watchtower container) then it has the ability to update itself. If a new version of the <code>containrrr/watchtower</code> image is pushed to the Docker Hub, your watchtower will pull down the new image and restart itself automatically.</p>"},{"location":"usage-overview/","title":"Usage overview","text":"<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 containrrr Docker Hub.</p> <p>Since the watchtower code needs to interact with the Docker API in order to monitor the running containers, you need to mount /var/run/docker.sock 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> <pre><code>docker run -d \\\n --name watchtower \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n containrrr/watchtower\n</code></pre> <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> <p>Passing environment variables:</p> <pre><code>docker run -d \\\n --name watchtower \\\n -e REPO_USER=username \\\n -e REPO_PASS=password \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n containrrr/watchtower container_to_watch --debug\n</code></pre> <p>Also check out this Stack Overflow answer for more options on how to pass environment variables.</p> <p>Alternatively if you 2FA authentication setup on Docker Hub then passing username and password will be insufficient. Instead you can run <code>docker login</code> to store your credentials in <code>$HOME/.docker/config.json</code> and then mount this config file to make it available to the Watchtower container:</p> <pre><code>docker run -d \\\n --name watchtower \\\n -v $HOME/.docker/config.json:/config.json \\\n -v /var/run/docker.sock:/var/run/docker.sock \\\n containrrr/watchtower container_to_watch --debug\n</code></pre> <p>Changes to config.json while running</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 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 breaks the bind mount. As a workaround, 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 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 on the GitHub Registry and monitors it with watchtower. Note the command argument changing the interval to 30s rather than the default 24 hours.</p> <pre><code>version: \"3\"\nservices:\n cavo:\n image: ghcr.io/<org>/<image>:<tag>\n ports:\n - \"443:3443\"\n - \"80:3080\"\n watchtower:\n image: containrrr/watchtower\n volumes:\n - /var/run/docker.sock:/var/run/docker.sock\n - /root/.docker/config.json:/config.json\n command: --interval 30\n</code></pre>"}]} |