watchtower/search/search_index.json

{"config":{"lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Watchtower A container-based solution for automating Docker container base image updates. Quick Start \u00b6 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: $ docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ containrrr/watchtower","title":"Home"},{"location":"#quick_start","text":"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: $ docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ containrrr/watchtower","title":"Quick Start"},{"location":"arguments/","text":"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 --host 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. $ docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ containrrr/watchtower \\ nginx redis 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 --run-once flag and remove the watchtower container after its execution. $ docker run --rm \\ -v /var/run/docker.sock:/var/run/docker.sock \\ containrrr/watchtower \\ --run-once \\ nginx redis 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 --rm flag. When no arguments are specified, watchtower will monitor all running containers. Help \u00b6 Shows documentation about the supported flags. Argument: --help Environment Variable: N/A Type: N/A Default: N/A Time Zone \u00b6 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 timezome can alternatively be set by volume mounting your hosts /etc/timezone file. -v /etc/timezone:/etc/timezone:ro Argument: N/A Environment Variable: TZ Type: String Default: \"UTC\" Cleanup \u00b6 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. Argument: --cleanup Environment Variable: WATCHTOWER_CLEANUP Type: Boolean Default: false Remove attached volumes \u00b6 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. Argument: --remove-volumes Environment Variable: WATCHTOWER_REMOVE_VOLUMES Type: Boolean Default: false Debug \u00b6 Enable debug mode with verbose logging. Argument: --debug, -d Environment Variable: WATCHTOWER_DEBUG Type: Boolean Default: false Trace \u00b6 Enable trace mode with very verbose logging. Caution: exposes credentials! Argument: --trace Environment Variable: WATCHTOWER_TRACE Type: Boolean Default: false Docker host \u00b6 Docker daemon socket to connect to. Can be pointed at a remote Docker host by specifying a TCP endpoint as \"tcp://hostname:port\". Argument: --host, -h Environment Variable: DOCKER_HOST Type: String Default: \"unix:///var/run/docker.sock\" Docker API version \u00b6 The API version to use by the Docker client for connecting to the Docker daemon. The minimum supported version is 1.24. Argument: --api-version, -a Environment Variable: DOCKER_API_VERSION Type: String Default: \"1.24\" Include stopped \u00b6 Will also include created and exited containers. Argument: --include-stopped Environment Variable: WATCHTOWER_INCLUDE_STOPPED Type: Boolean Default: false Revive stopped \u00b6 Start any stopped containers that have had their image updated. This argument is only usable with the --include-stopped argument. Argument: --revive-stopped Environment Variable: WATCHTOWER_REVIVE_STOPPED Type: Boolean Default: false Poll interval \u00b6 Poll interval (in seconds). This value controls how frequently watchtower will poll for new images. Either --schedule or a poll interval can be defined, but not both. Argument: --interval, -i Environment Variable: WATCHTOWER_POLL_INTERVAL Type: Integer Default: 300 Filter by enable label \u00b6 Update containers that have a com.centurylinklabs.watchtower.enable label set to true. Argument: --label-enable Environment Variable: WATCHTOWER_LABEL_ENABLE Type: Boolean Default: false Filter by disable label \u00b6 Do not update containers that have com.centurylinklabs.watchtower.enable label set to false and no --label-enable argument is passed. Note that only one or the other (targeting by enable label) can be used at the same time to target containers. Without updating containers \u00b6 Will only monitor for new images, not update the containers. \u26a0\ufe0f Please note \u00b6 Due to Docker API limitations the latest image will still be pulled from the registry. Argument: --monitor-only Environment Variable: WATCHTOWER_MONITOR_ONLY Type: Boolean Default: false Without restarting containers \u00b6 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. Argument: --no-restart Environment Variable: WATCHTOWER_NO_RESTART Type: Boolean Default: false Without pulling new images \u00b6 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. Argument: --no-pull Environment Variable: WATCHTOWER_NO_PULL Type: Boolean Default: false Without sending a startup message \u00b6 Do not send a message after watchtower started. Otherwise there will be an info-level notification. Argument: --no-startup-message Environment Variable: WATCHTOWER_NO_STARTUP_MESSAGE Type: Boolean Default: false Run once \u00b6 Run an update attempt against a container name list one time immediately and exit. Argument: --run-once Environment Variable: WATCHTOWER_RUN_ONCE Type: Boolean Default: false HTTP API Mode \u00b6 Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. Argument: --http-api Environment Variable: WATCHTOWER_HTTP_API Type: Boolean Default: false HTTP API Token \u00b6 Sets an authentication token to HTTP API requests. Argument: --http-api-token Environment Variable: WATCHTOWER_HTTP_API_TOKEN Type: String Default: - Scheduling \u00b6 Cron expression in 6 fields (rather than the traditional 5) which defines when and how often to check for new images. Either --interval or the schedule expression can be defined, but not both. An example: --schedule \"0 0 4 * * *\" Argument: --schedule, -s Environment Variable: WATCHTOWER_SCHEDULE Type: String Default: - Wait until timeout \u00b6 Timeout before the container is forcefully stopped. When set, this option will change the default ( 10s ) wait time to the given value. An example: --stop-timeout 30s will set the timeout to 30 seconds. Argument: --stop-timeout Environment Variable: WATCHTOWER_TIMEOUT Type: Duration Default: 10s TLS Verification \u00b6 Use TLS when connecting to the Docker socket and verify the server's certificate. See below for options used to configure notifications. Argument: --tlsverify Environment Variable: DOCKER_TLS_VERIFY Type: Boolean Default: false","title":"Arguments"},{"location":"arguments/#help","text":"Shows documentation about the supported flags. Argument: --help Environment Variable: N/A Type: N/A Default: N/A","title":"Help"},{"location":"arguments/#time_zone","text":"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 timezome can alternatively be set by volume mounting your hosts /etc/timezone file. -v /etc/timezone:/etc/timezone:ro Argument: N/A Environment Variable: TZ Type: String Default: \"UTC\"","title":"Time Zone"},{"location":"arguments/#cleanup","text":"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. Argument: --cleanup Environment Variable: WATCHTOWER_CLEANUP Type: Boolean Default: false","title":"Cleanup"},{"location":"arguments/#remove_attached_volumes","text":"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. Argument: --remove-volumes Environment Variable: WATCHTOWER_REMOVE_VOLUMES Type: Boolean Default: false","title":"Remove attached volumes"},{"location":"arguments/#debug","text":"Enable debug mode with verbose logging. Argument: --debug, -d Environment Variable: WATCHTOWER_DEBUG Type: Boolean Default: false","title":"Debug"},{"location":"arguments/#trace","text":"Enable trace mode with very verbose logging. Caution: exposes credentials! Argument: --trace Environment Variable: WATCHTOWER_TRACE Type: Boolean Default: false","title":"Trace"},{"location":"arguments/#docker_host","text":"Docker daemon socket to connect to. Can be pointed at a remote Docker host by specifying a TCP endpoint as \"tcp://hostname:port\". Argument: --host, -h Environment Variable: DOCKER_HOST Type: String Default: \"unix:///var/run/docker.sock\"","title":"Docker host"},{"location":"arguments/#docker_api_version","text":"The API version to use by the Docker client for connecting to the Docker daemon. The minimum supported version is 1.24. Argument: --api-version, -a Environment Variable: DOCKER_API_VERSION Type: String Default: \"1.24\"","title":"Docker API version"},{"location":"arguments/#include_stopped","text":"Will also include created and exited containers. Argument: --include-stopped Environment Variable: WATCHTOWER_INCLUDE_STOPPED Type: Boolean Default: false","title":"Include stopped"},{"location":"arguments/#revive_stopped","text":"Start any stopped containers that have had their image updated. This argument is only usable with the --include-stopped argument. Argument: --revive-stopped Environment Variable: WATCHTOWER_REVIVE_STOPPED Type: Boolean Default: false","title":"Revive stopped"},{"location":"arguments/#poll_interval","text":"Poll interval (in seconds). This value controls how frequently watchtower will poll for new images. Either --schedule or a poll interval can be defined, but not both. Argument: --interval, -i Environment Variable: WATCHTOWER_POLL_INTERVAL Type: Integer Default: 300","title":"Poll interval"},{"location":"arguments/#filter_by_enable_label","text":"Update containers that have a com.centurylinklabs.watchtower.enable label set to true. Argument: --label-enable Environment Variable: WATCHTOWER_LABEL_ENABLE Type: Boolean Default: false","title":"Filter by enable label"},{"location":"arguments/#filter_by_disable_label","text":"Do not update containers that have com.centurylinklabs.watchtower.enable label set to false and no --label-enable argument is passed. Note that only one or the other (targeting by enable label) can be used at the same time to target containers.","title":"Filter by disable label"},{"location":"arguments/#without_updating_containers","text":"Will only monitor for new images, not update the containers.","title":"Without updating containers"},{"location":"arguments/#please_note","text":"Due to Docker API limitations the latest image will still be pulled from the registry. Argument: --monitor-only Environment Variable: WATCHTOWER_MONITOR_ONLY Type: Boolean Default: false","title":"\u26a0\ufe0f Please note"},{"location":"arguments/#without_restarting_containers","text":"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. Argument: --no-restart Environment Variable: WATCHTOWER_NO_RESTART Type: Boolean Default: false","title":"Without restarting containers"},{"location":"arguments/#without_pulling_new_images","text":"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. Argument: --no-pull Environment Variable: WATCHTOWER_NO_PULL Type: Boolean Default: false","title":"Without pulling new images"},{"location":"arguments/#without_sending_a_startup_message","text":"Do not send a message after watchtower started. Otherwise there will be an info-level notification. Argument: --no-startup-message Environment Variable: WATCHTOWER_NO_STARTUP_MESSAGE Type: Boolean Default: false","title":"Without sending a startup message"},{"location":"arguments/#run_once","text":"Run an update attempt against a container name list one time immediately and exit. Argument: --run-once Environment Variable: WATCHTOWER_RUN_ONCE Type: Boolean Default: false","title":"Run once"},{"location":"arguments/#http_api_mode","text":"Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. Argument: --http-api Environment Variable: WATCHTOWER_HTTP_API Type: Boolean Default: false","title":"HTTP API Mode"},{"location":"arguments/#http_api_token","text":"Sets an authentication token to HTTP API requests. Argument: --http-api-token Environment Variable: WATCHTOWER_HTTP_API_TOKEN Type: String Default: -","title":"HTTP API Token"},{"location":"arguments/#scheduling","text":"Cron expression in 6 fields (rather than the traditional 5) which defines when and how often to check for new images. Either --interval or the schedule expression can be defined, but not both. An example: --schedule \"0 0 4 * * *\" Argument: --schedule, -s Environment Variable: WATCHTOWER_SCHEDULE Type: String Default: -","title":"Scheduling"},{"location":"arguments/#wait_until_timeout","text":"Timeout before the container is forcefully stopped. When set, this option will change the default ( 10s ) wait time to the given value. An example: --stop-timeout 30s will set the timeout to 30 seconds. Argument: --stop-timeout Environment Variable: WATCHTOWER_TIMEOUT Type: Duration Default: 10s","title":"Wait until timeout"},{"location":"arguments/#tls_verification","text":"Use TLS when connecting to the Docker socket and verify the server's certificate. See below for options used to configure notifications. Argument: --tlsverify Environment Variable: DOCKER_TLS_VERIFY Type: Boolean Default: false","title":"TLS Verification"},{"location":"container-selection/","text":"By default, watchtower will watch all containers. However, sometimes only some containers should be updated. If you need to exclude some containers, set the com.centurylinklabs.watchtower.enable label to false . LABEL com.centurylinklabs.watchtower.enable=\"false\" Or, it can be specified as part of the docker run command line: docker run -d --label=com.centurylinklabs.watchtower.enable=false someimage If you need to include only containers with the enable label , pass the --label-enable flag or the WATCTOWER_LABEL_ENABLE environment variable on startup and set the com.centurylinklabs.watchtower.enable label with a value of true for the containers you want to watch. LABEL com.centurylinklabs.watchtower.enable=\"true\" Or, it can be specified as part of the docker run command line: docker run -d --label=com.centurylinklabs.watchtower.enable=true someimage","title":"Container selection"},{"location":"http-api-mode/","text":"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: /v1/update - triggers an update for all of the containers monitored by this Watchtower instance. To enable this mode, use the flag --http-api . For example, in a Docker Compose config file: version: '3' services: app-monitored-by-watchtower: image: myapps/monitored-by-watchtower labels: - \"com.centurylinklabs.watchtower.enable=true\" watchtower: image: containrrr/watchtower volumes: - /var/run/docker.sock:/var/run/docker.sock command: --debug --http-api environment: - WATCHTOWER_HTTP_API_TOKEN=mytoken labels: - \"com.centurylinklabs.watchtower.enable=false\" ports: - 8080:8080 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 curl command would trigger an image update: curl -H \"Token: mytoken\" localhost:8080/v1/update","title":"Http api mode"},{"location":"introduction/","text":"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. 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. For example, let's say you were running watchtower along with an instance of centurylink/wetty-cli image: $ docker ps CONTAINER ID IMAGE STATUS PORTS NAMES 967848166a45 centurylink/wetty-cli Up 10 minutes 0.0.0.0:8080->3000/tcp wetty 6cc4d2a9d1a5 containrrr/watchtower Up 15 minutes watchtower Every few minutes 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 docker run options that were used to start the container initially (in this case, that would include the -p 8080:3000 port mapping).","title":"Introduction"},{"location":"lifecycle-hooks/","text":"Executing commands before and after updating \u00b6 DO NOTE : These are shell commands executed with sh , and therefore require the container to provide the sh executable. It is possible to execute pre/post-check and pre/post-update commands inside every container updated by watchtower. The pre-check command is executed for each container prior to every update cycle. The pre-update command is executed before stopping the container when an update is about to start. The post-update command is executed after restarting the updated container The post-check command is executed for each container post every update cycle. This feature is disabled by default. To enable it, you need to set the option --enable-lifecycle-hooks on the command line, or set the environment variable WATCHTOWER_LIFECYCLE_HOOKS to true . Specifying update commands \u00b6 The commands are specified using docker container labels, the following are currently available: Type Docker Container Label Pre Check com.centurylinklabs.watchtower.lifecycle.pre-check Pre Update com.centurylinklabs.watchtower.lifecycle.pre-update Post Update com.centurylinklabs.watchtower.lifecycle.post-update Post Check com.centurylinklabs.watchtower.lifecycle.post-check These labels can be declared as instructions in a Dockerfile (with some example .sh files): LABEL com.centurylinklabs.watchtower.lifecycle.pre-check=\"/sync.sh\" LABEL com.centurylinklabs.watchtower.lifecycle.pre-update=\"/dump-data.sh\" LABEL com.centurylinklabs.watchtower.lifecycle.post-update=\"/restore-data.sh\" LABEL com.centurylinklabs.watchtower.lifecycle.post-check=\"/send-heartbeat.sh\" Or be specified as part of the docker run command line: docker run -d \\ --label=com.centurylinklabs.watchtower.lifecycle.pre-check=\"/sync.sh\" \\ --label=com.centurylinklabs.watchtower.lifecycle.pre-update=\"/dump-data.sh\" \\ --label=com.centurylinklabs.watchtower.lifecycle.post-update=\"/restore-data.sh\" \\ someimage --label=com.centurylinklabs.watchtower.lifecycle.post-check=\"/send-heartbeat.sh\" \\ Timeouts \u00b6 The timeout for all lifecycle commands is 60 seconds. After that, a timeout will occur, forcing Watchtower to continue the update loop. Pre-update timeouts \u00b6 For the pre-update 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 com.centurylinklabs.watchtower.lifecycle.pre-update-timeout followed by the timeout expressed in minutes. If the label value is explicitly set to 0 , the timeout will be disabled. Execution failure \u00b6 The failure of a command to execute, identified by an exit code different than 0, will not prevent watchtower from updating the container. Only an error log statement containing the exit code will be reported.","title":"Lifecycle hooks"},{"location":"lifecycle-hooks/#executing_commands_before_and_after_updating","text":"DO NOTE : These are shell commands executed with sh , and therefore require the container to provide the sh executable. It is possible to execute pre/post-check and pre/post-update commands inside every container updated by watchtower. The pre-check command is executed for each container prior to every update cycle. The pre-update command is executed before stopping the container when an update is about to start. The post-update command is executed after restarting the updated container The post-check command is executed for each container post every update cycle. This feature is disabled by default. To enable it, you need to set the option --enable-lifecycle-hooks on the command line, or set the environment variable WATCHTOWER_LIFECYCLE_HOOKS to true .","title":"Executing commands before and after updating"},{"location":"lifecycle-hooks/#specifying_update_commands","text":"The commands are specified using docker container labels, the following are currently available: Type Docker Container Label Pre Check com.centurylinklabs.watchtower.lifecycle.pre-check Pre Update com.centurylinklabs.watchtower.lifecycle.pre-update Post Update com.centurylinklabs.watchtower.lifecycle.post-update Post Check com.centurylinklabs.watchtower.lifecycle.post-check These labels can be declared as instructions in a Dockerfile (with some example .sh files): LABEL com.centurylinklabs.watchtower.lifecycle.pre-check=\"/sync.sh\" LABEL com.centurylinklabs.watchtower.lifecycle.pre-update=\"/dump-data.sh\" LABEL com.centurylinklabs.watchtower.lifecycle.post-update=\"/restore-data.sh\" LABEL com.centurylinklabs.watchtower.lifecycle.post-check=\"/send-heartbeat.sh\" Or be specified as part of the docker run command line: docker run -d \\ --label=com.centurylinklabs.watchtower.lifecycle.pre-check=\"/sync.sh\" \\ --label=com.centurylinklabs.watchtower.lifecycle.pre-update=\"/dump-data.sh\" \\ --label=com.centurylinklabs.watchtower.lifecycle.post-update=\"/restore-data.sh\" \\ someimage --label=com.centurylinklabs.watchtower.lifecycle.post-check=\"/send-heartbeat.sh\" \\","title":"Specifying update commands"},{"location":"lifecycle-hooks/#timeouts","text":"The timeout for all lifecycle commands is 60 seconds. After that, a timeout will occur, forcing Watchtower to continue the update loop.","title":"Timeouts"},{"location":"lifecycle-hooks/#pre-update_timeouts","text":"For the pre-update 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 com.centurylinklabs.watchtower.lifecycle.pre-update-timeout followed by the timeout expressed in minutes. If the label value is explicitly set to 0 , the timeout will be disabled.","title":"Pre-update timeouts"},{"location":"lifecycle-hooks/#execution_failure","text":"The failure of a command to execute, identified by an exit code different than 0, will not prevent watchtower from updating the container. Only an error log statement containing the exit code will be reported.","title":"Execution failure"},{"location":"linked-containers/","text":"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. 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. If you want to override existing links you can use special com.centurylinklabs.watchtower.depends-on label with dependent container names, separated by a comma.","title":"Linked containers"},{"location":"notifications/","text":"Notifications \u00b6 Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging system, logrus . The types of notifications to send are set by passing a comma-separated list of values to the --notifications option (or corresponding environment variable WATCHTOWER_NOTIFICATIONS ), which has the following valid values: email to send notifications via e-mail slack to send notifications through a Slack webhook msteams to send notifications via MSTeams webhook gotify to send notifications via Gotify shoutrrr to send notifications via containrrr/shoutrrr There is currently a bug 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 WATCHTOWER_NOTIFICATIONS=\"slack msteams\" If you're a docker-compose user, make sure to specify environment variables' values in your .yml file without double quotes ( \" ). This prevents unexpected errors when watchtower starts. Settings \u00b6 --notifications-level (env. WATCHTOWER_NOTIFICATIONS_LEVEL ): Controls the log level which is used for the notifications. If omitted, the default log level is info . Possible values are: panic , fatal , error , warn , info , debug or trace . Watchtower will post a notification every time it is started. This behavior can be changed with an argument. Available services \u00b6 Email \u00b6 To receive notifications by email, the following command-line options, or their corresponding environment variables, can be set: --notification-email-from (env. WATCHTOWER_NOTIFICATION_EMAIL_FROM ): The e-mail address from which notifications will be sent. --notification-email-to (env. WATCHTOWER_NOTIFICATION_EMAIL_TO ): The e-mail address to which notifications will be sent. --notification-email-server (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER ): The SMTP server to send e-mails through. --notification-email-server-tls-skip-verify (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY ): Do not verify the TLS certificate of the mail server. This should be used only for testing. --notification-email-server-port (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT ): The port used to connect to the SMTP server to send e-mails through. Defaults to 25 . --notification-email-server-user (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER ): The username to authenticate with the SMTP server with. --notification-email-server-password (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD ): The password to authenticate with the SMTP server with. --notification-email-delay (env. WATCHTOWER_NOTIFICATION_EMAIL_DELAY ): Delay before sending notifications expressed in seconds. --notification-email-subjecttag (env. WATCHTOWER_NOTIFICATION_EMAIL_SUBJECTTAG ): Prefix to include in the subject tag. Useful when running multiple watchtowers. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=email \\ -e WATCHTOWER_NOTIFICATION_EMAIL_FROM=fromaddress@gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_TO=toaddress@gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=fromaddress@gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=app_password \\ -e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=2 \\ containrrr/watchtower 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 docker-compose.yml might be a good start for you. The following example assumes, that your domain is called your-domain.com and that you are going to use a certificate valid for smtp.your-domain.com . This hostname has to be used as WATCHTOWER_NOTIFICATION_EMAIL_SERVER otherwise the TLS connection is going to fail with Failed to send notification email or connect: connection refused . 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 . Example including an SMTP relay: --- version: \"3.8\" services: watchtower: image: containrrr/watchtower:latest container_name: watchtower environment: WATCHTOWER_MONITOR_ONLY: \"true\" WATCHTOWER_NOTIFICATIONS: email WATCHTOWER_NOTIFICATION_EMAIL_FROM: from-address@your-domain.com WATCHTOWER_NOTIFICATION_EMAIL_TO: to-address@your-domain.com # you have to use a network alias here, if you use your own certificate WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.your-domain.com WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 25 WATCHTOWER_NOTIFICATION_EMAIL_DELAY: 2 volumes: - /var/run/docker.sock:/var/run/docker.sock networks: - watchtower depends_on: - postfix # SMTP needed to send out status emails postfix: image: freinet/postfix-relay:latest expose: - 25 environment: MAILNAME: somename.your-domain.com TLS_KEY: \"/etc/ssl/domains/your-domain.com/your-domain.com.key\" TLS_CRT: \"/etc/ssl/domains/your-domain.com/your-domain.com.crt\" TLS_CA: \"/etc/ssl/domains/your-domain.com/intermediate.crt\" volumes: - /etc/ssl/domains/your-domain.com/:/etc/ssl/domains/your-domain.com/:ro networks: watchtower: # this alias is really important to make your certificate work aliases: - smtp.your-domain.com networks: watchtower: external: false Slack \u00b6 If watchtower is monitoring the same Docker daemon under which the watchtower container itself is running (i.e. if you volume-mounted /var/run/docker.sock into the watchtower container) then it has the ability to update itself. If a new version of the containrrr/watchtower image is pushed to the Docker Hub, your watchtower will pull down the new image and restart itself automatically. To receive notifications in Slack, add slack to the --notifications option or the WATCHTOWER_NOTIFICATIONS environment variable. Additionally, you should set the Slack webhook URL using the --notification-slack-hook-url option or the WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL environment variable. By default, watchtower will send messages under the name watchtower , you can customize this string through the --notification-slack-identifier option or the WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER environment variable. Other, optional, variables include: --notification-slack-channel (env. WATCHTOWER_NOTIFICATION_SLACK_CHANNEL ): A string which overrides the webhook's default channel. Example: #my-custom-channel. --notification-slack-icon-emoji (env. WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI ): An emoji code string to use in place of the default icon. --notification-slack-icon-url (env. WATCHTOWER_NOTIFICATION_SLACK_ICON_URL ): An icon image URL string to use in place of the default icon. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=slack \\ -e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=\"https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy\" \\ -e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server-1 \\ -e WATCHTOWER_NOTIFICATION_SLACK_CHANNEL=#my-custom-channel \\ -e WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI=:whale: \\ -e WATCHTOWER_NOTIFICATION_SLACK_ICON_URL=<icon url> \\ containrrr/watchtower Microsoft Teams \u00b6 To receive notifications in MSTeams channel, add msteams to the --notifications option or the WATCHTOWER_NOTIFICATIONS environment variable. Additionally, you should set the MSTeams webhook URL using the --notification-msteams-hook option or the WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL environment variable. MSTeams notifier could send keys/values filled by log.WithField or log.WithFields as MSTeams message facts. To enable this feature add --notification-msteams-data flag or set WATCHTOWER_NOTIFICATION_MSTEAMS_USE_LOG_DATA=true environment variable. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=msteams \\ -e WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL=\"https://outlook.office.com/webhook/xxxxxxxx@xxxxxxx/IncomingWebhook/yyyyyyyy/zzzzzzzzzz\" \\ -e WATCHTOWER_NOTIFICATION_MSTEAMS_USE_LOG_DATA=true \\ containrrr/watchtower Gotify \u00b6 To push a notification to your Gotify instance, register a Gotify app and specify the Gotify URL and app token: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=gotify \\ -e WATCHTOWER_NOTIFICATION_GOTIFY_URL=\"https://my.gotify.tld/\" \\ -e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN=\"SuperSecretToken\" \\ containrrr/watchtower If you want to disable TLS verification for the Gotify instance, you can use either -e WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY=true or --notification-gotify-tls-skip-verify . containrrr/shoutrrr \u00b6 To send notifications via shoutrrr, the following command-line options, or their corresponding environment variables, can be set: --notification-url (env. WATCHTOWER_NOTIFICATION_URL ): The shoutrrr service URL to be used. Go to containrrr.github.io/shoutrrr/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) You can customize the message posted by setting a template. --notification-template (env. WATCHTOWER_NOTIFICATION_TEMPLATE ): The template used for the message. The template is a Go template and the you format a list of log entries . The default value if not set is {{range .}}{{.Message}}{{println}}{{end}} . The example below uses a template that also outputs timestamp and log level. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=shoutrrr \\ -e WATCHTOWER_NOTIFICATION_URL=\"discord://token@channel slack://watchtower@token-a/token-b/token-c\" \\ -e WATCHTOWER_NOTIFICATION_TEMPLATE=\"{{range .}}{{.Time.Format \\\"2006-01-02 15:04:05\\\"}} ({{.Level}}): {{.Message}}{{println}}{{end}}\" \\ containrrr/watchtower","title":"Notifications"},{"location":"notifications/#notifications","text":"Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging system, logrus . The types of notifications to send are set by passing a comma-separated list of values to the --notifications option (or corresponding environment variable WATCHTOWER_NOTIFICATIONS ), which has the following valid values: email to send notifications via e-mail slack to send notifications through a Slack webhook msteams to send notifications via MSTeams webhook gotify to send notifications via Gotify shoutrrr to send notifications via containrrr/shoutrrr There is currently a bug 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 WATCHTOWER_NOTIFICATIONS=\"slack msteams\" If you're a docker-compose user, make sure to specify environment variables' values in your .yml file without double quotes ( \" ). This prevents unexpected errors when watchtower starts.","title":"Notifications"},{"location":"notifications/#settings","text":"--notifications-level (env. WATCHTOWER_NOTIFICATIONS_LEVEL ): Controls the log level which is used for the notifications. If omitted, the default log level is info . Possible values are: panic , fatal , error , warn , info , debug or trace . Watchtower will post a notification every time it is started. This behavior can be changed with an argument.","title":"Settings"},{"location":"notifications/#available_services","text":"","title":"Available services"},{"location":"notifications/#email","text":"To receive notifications by email, the following command-line options, or their corresponding environment variables, can be set: --notification-email-from (env. WATCHTOWER_NOTIFICATION_EMAIL_FROM ): The e-mail address from which notifications will be sent. --notification-email-to (env. WATCHTOWER_NOTIFICATION_EMAIL_TO ): The e-mail address to which notifications will be sent. --notification-email-server (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER ): The SMTP server to send e-mails through. --notification-email-server-tls-skip-verify (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY ): Do not verify the TLS certificate of the mail server. This should be used only for testing. --notification-email-server-port (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT ): The port used to connect to the SMTP server to send e-mails through. Defaults to 25 . --notification-email-server-user (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER ): The username to authenticate with the SMTP server with. --notification-email-server-password (env. WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD ): The password to authenticate with the SMTP server with. --notification-email-delay (env. WATCHTOWER_NOTIFICATION_EMAIL_DELAY ): Delay before sending notifications expressed in seconds. --notification-email-subjecttag (env. WATCHTOWER_NOTIFICATION_EMAIL_SUBJECTTAG ): Prefix to include in the subject tag. Useful when running multiple watchtowers. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=email \\ -e WATCHTOWER_NOTIFICATION_EMAIL_FROM=fromaddress@gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_TO=toaddress@gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=fromaddress@gmail.com \\ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=app_password \\ -e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=2 \\ containrrr/watchtower 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 docker-compose.yml might be a good start for you. The following example assumes, that your domain is called your-domain.com and that you are going to use a certificate valid for smtp.your-domain.com . This hostname has to be used as WATCHTOWER_NOTIFICATION_EMAIL_SERVER otherwise the TLS connection is going to fail with Failed to send notification email or connect: connection refused . 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 . Example including an SMTP relay: --- version: \"3.8\" services: watchtower: image: containrrr/watchtower:latest container_name: watchtower environment: WATCHTOWER_MONITOR_ONLY: \"true\" WATCHTOWER_NOTIFICATIONS: email WATCHTOWER_NOTIFICATION_EMAIL_FROM: from-address@your-domain.com WATCHTOWER_NOTIFICATION_EMAIL_TO: to-address@your-domain.com # you have to use a network alias here, if you use your own certificate WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.your-domain.com WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 25 WATCHTOWER_NOTIFICATION_EMAIL_DELAY: 2 volumes: - /var/run/docker.sock:/var/run/docker.sock networks: - watchtower depends_on: - postfix # SMTP needed to send out status emails postfix: image: freinet/postfix-relay:latest expose: - 25 environment: MAILNAME: somename.your-domain.com TLS_KEY: \"/etc/ssl/domains/your-domain.com/your-domain.com.key\" TLS_CRT: \"/etc/ssl/domains/your-domain.com/your-domain.com.crt\" TLS_CA: \"/etc/ssl/domains/your-domain.com/intermediate.crt\" volumes: - /etc/ssl/domains/your-domain.com/:/etc/ssl/domains/your-domain.com/:ro networks: watchtower: # this alias is really important to make your certificate work aliases: - smtp.your-domain.com networks: watchtower: external: false","title":"Email"},{"location":"notifications/#slack","text":"If watchtower is monitoring the same Docker daemon under which the watchtower container itself is running (i.e. if you volume-mounted /var/run/docker.sock into the watchtower container) then it has the ability to update itself. If a new version of the containrrr/watchtower image is pushed to the Docker Hub, your watchtower will pull down the new image and restart itself automatically. To receive notifications in Slack, add slack to the --notifications option or the WATCHTOWER_NOTIFICATIONS environment variable. Additionally, you should set the Slack webhook URL using the --notification-slack-hook-url option or the WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL environment variable. By default, watchtower will send messages under the name watchtower , you can customize this string through the --notification-slack-identifier option or the WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER environment variable. Other, optional, variables include: --notification-slack-channel (env. WATCHTOWER_NOTIFICATION_SLACK_CHANNEL ): A string which overrides the webhook's default channel. Example: #my-custom-channel. --notification-slack-icon-emoji (env. WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI ): An emoji code string to use in place of the default icon. --notification-slack-icon-url (env. WATCHTOWER_NOTIFICATION_SLACK_ICON_URL ): An icon image URL string to use in place of the default icon. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=slack \\ -e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=\"https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy\" \\ -e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server-1 \\ -e WATCHTOWER_NOTIFICATION_SLACK_CHANNEL=#my-custom-channel \\ -e WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI=:whale: \\ -e WATCHTOWER_NOTIFICATION_SLACK_ICON_URL=<icon url> \\ containrrr/watchtower","title":"Slack"},{"location":"notifications/#microsoft_teams","text":"To receive notifications in MSTeams channel, add msteams to the --notifications option or the WATCHTOWER_NOTIFICATIONS environment variable. Additionally, you should set the MSTeams webhook URL using the --notification-msteams-hook option or the WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL environment variable. MSTeams notifier could send keys/values filled by log.WithField or log.WithFields as MSTeams message facts. To enable this feature add --notification-msteams-data flag or set WATCHTOWER_NOTIFICATION_MSTEAMS_USE_LOG_DATA=true environment variable. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=msteams \\ -e WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL=\"https://outlook.office.com/webhook/xxxxxxxx@xxxxxxx/IncomingWebhook/yyyyyyyy/zzzzzzzzzz\" \\ -e WATCHTOWER_NOTIFICATION_MSTEAMS_USE_LOG_DATA=true \\ containrrr/watchtower","title":"Microsoft Teams"},{"location":"notifications/#gotify","text":"To push a notification to your Gotify instance, register a Gotify app and specify the Gotify URL and app token: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=gotify \\ -e WATCHTOWER_NOTIFICATION_GOTIFY_URL=\"https://my.gotify.tld/\" \\ -e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN=\"SuperSecretToken\" \\ containrrr/watchtower If you want to disable TLS verification for the Gotify instance, you can use either -e WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY=true or --notification-gotify-tls-skip-verify .","title":"Gotify"},{"location":"notifications/#containrrrshoutrrr","text":"To send notifications via shoutrrr, the following command-line options, or their corresponding environment variables, can be set: --notification-url (env. WATCHTOWER_NOTIFICATION_URL ): The shoutrrr service URL to be used. Go to containrrr.github.io/shoutrrr/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) You can customize the message posted by setting a template. --notification-template (env. WATCHTOWER_NOTIFICATION_TEMPLATE ): The template used for the message. The template is a Go template and the you format a list of log entries . The default value if not set is {{range .}}{{.Message}}{{println}}{{end}} . The example below uses a template that also outputs timestamp and log level. Example: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ -e WATCHTOWER_NOTIFICATIONS=shoutrrr \\ -e WATCHTOWER_NOTIFICATION_URL=\"discord://token@channel slack://watchtower@token-a/token-b/token-c\" \\ -e WATCHTOWER_NOTIFICATION_TEMPLATE=\"{{range .}}{{.Time.Format \\\"2006-01-02 15:04:05\\\"}} ({{.Level}}): {{.Message}}{{println}}{{end}}\" \\ containrrr/watchtower","title":"containrrr/shoutrrr"},{"location":"private-registries/","text":"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. The credentials can be provided to watchtower in a configuration file called config.json . There are two ways to generate this configuration file: The configuration file can be created manually. Call docker login <REGISTRY_NAME> and share the resulting configuration file. Create the configuration file manually \u00b6 Create a new configuration file with the following syntax and a base64 encoded username and password auth string: { \"auths\": { \"<REGISTRY_NAME>\": { \"auth\": \"XXXXXXX\" } } } <REGISTRY_NAME> needs to be replaced by the name of your private registry (e.g., my-private-registry.example.org ) The required auth string can be generated as follows: echo -n 'username:password' | base64 \u2139\ufe0f Username and Password for GCloud \u00b6 For gcloud, we'll use __json_key as our username and the content of gcloudauth.json as the password. When the watchtower Docker container is started, the created configuration file ( <PATH>/config.json in this example) needs to be passed to the container: docker run [...] -v <PATH>/config.json:/config.json containrrr/watchtower Share the Docker configuration file \u00b6 To pull an image from a private registry, docker login needs to be called first, to get access to the registry. The provided credentials are stored in a configuration file called <PATH_TO_HOME_DIR>/.docker/config.json . This configuration file can be directly used by watchtower. In this case, the creation of an additional configuration file is not necessary. When the Docker container is started, pass the configuration file to watchtower: docker run [...] -v <PATH_TO_HOME_DIR>/.docker/config.json:/config.json containrrr/watchtower When creating the watchtower container via docker-compose, use the following lines: version: \"3\" [...] watchtower: image: index.docker.io/containrrr/watchtower:latest volumes: - /var/run/docker.sock:/var/run/docker.sock - <PATH_TO_HOME_DIR>/.docker/config.json:/config.json [...] Credential helpers \u00b6 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. 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. Example \u00b6 Example implementation for use with amazon-ecr-credential-helper : FROM golang:latest ENV CGO_ENABLED 0 ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login RUN go get -u $REPO RUN rm /go/bin/docker-credential-ecr-login RUN go build \\ -o /go/bin/docker-credential-ecr-login \\ /go/src/$REPO WORKDIR /go/bin/ and the docker-compose definition: version: \"3\" services: watchtower: image: index.docker.io/containrrr/watchtower:latest volumes: - /var/run/docker.sock:/var/run/docker.sock - <PATH_TO_HOME_DIR>/.docker/config.json:/config.json - helper:/go/bin environment: - HOME=/ - PATH=$PATH:/go/bin - AWS_REGION=<AWS_REGION> - AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY> - AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> volumes: helper: {} and for <PATH_TO_HOME_DIR>/.docker/config.json : { \"HttpHeaders\" : { \"User-Agent\" : \"Docker-Client/19.03.1 (XXXXXX)\" }, \"credsStore\" : \"osxkeychain\", \"auths\" : { \"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com\" : {}, \"https://index.docker.io/v1/\": {} }, \"credHelpers\": { \"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com\" : \"ecr-login\", \"index.docker.io\": \"osxkeychain\" } } Note: osxkeychain can be changed to your preferred credentials helper.","title":"Private registries"},{"location":"private-registries/#create_the_configuration_file_manually","text":"Create a new configuration file with the following syntax and a base64 encoded username and password auth string: { \"auths\": { \"<REGISTRY_NAME>\": { \"auth\": \"XXXXXXX\" } } } <REGISTRY_NAME> needs to be replaced by the name of your private registry (e.g., my-private-registry.example.org ) The required auth string can be generated as follows: echo -n 'username:password' | base64","title":"Create the configuration file manually"},{"location":"private-registries/#i_username_and_password_for_gcloud","text":"For gcloud, we'll use __json_key as our username and the content of gcloudauth.json as the password. When the watchtower Docker container is started, the created configuration file ( <PATH>/config.json in this example) needs to be passed to the container: docker run [...] -v <PATH>/config.json:/config.json containrrr/watchtower","title":"\u2139\ufe0f Username and Password for GCloud"},{"location":"private-registries/#share_the_docker_configuration_file","text":"To pull an image from a private registry, docker login needs to be called first, to get access to the registry. The provided credentials are stored in a configuration file called <PATH_TO_HOME_DIR>/.docker/config.json . This configuration file can be directly used by watchtower. In this case, the creation of an additional configuration file is not necessary. When the Docker container is started, pass the configuration file to watchtower: docker run [...] -v <PATH_TO_HOME_DIR>/.docker/config.json:/config.json containrrr/watchtower When creating the watchtower container via docker-compose, use the following lines: version: \"3\" [...] watchtower: image: index.docker.io/containrrr/watchtower:latest volumes: - /var/run/docker.sock:/var/run/docker.sock - <PATH_TO_HOME_DIR>/.docker/config.json:/config.json [...]","title":"Share the Docker configuration file"},{"location":"private-registries/#credential_helpers","text":"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. 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.","title":"Credential helpers"},{"location":"private-registries/#example","text":"Example implementation for use with amazon-ecr-credential-helper : FROM golang:latest ENV CGO_ENABLED 0 ENV REPO github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login RUN go get -u $REPO RUN rm /go/bin/docker-credential-ecr-login RUN go build \\ -o /go/bin/docker-credential-ecr-login \\ /go/src/$REPO WORKDIR /go/bin/ and the docker-compose definition: version: \"3\" services: watchtower: image: index.docker.io/containrrr/watchtower:latest volumes: - /var/run/docker.sock:/var/run/docker.sock - <PATH_TO_HOME_DIR>/.docker/config.json:/config.json - helper:/go/bin environment: - HOME=/ - PATH=$PATH:/go/bin - AWS_REGION=<AWS_REGION> - AWS_ACCESS_KEY_ID=<AWS_ACCESS_KEY> - AWS_SECRET_ACCESS_KEY=<AWS_SECRET_ACCESS_KEY> volumes: helper: {} and for <PATH_TO_HOME_DIR>/.docker/config.json : { \"HttpHeaders\" : { \"User-Agent\" : \"Docker-Client/19.03.1 (XXXXXX)\" }, \"credsStore\" : \"osxkeychain\", \"auths\" : { \"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com\" : {}, \"https://index.docker.io/v1/\": {} }, \"credHelpers\": { \"xyzxyzxyz.dkr.ecr.eu-north-1.amazonaws.com\" : \"ecr-login\", \"index.docker.io\": \"osxkeychain\" } } Note: osxkeychain can be changed to your preferred credentials helper.","title":"Example"},{"location":"remote-hosts/","text":"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 --host flag or the DOCKER_HOST environment variable: docker run -d \\ --name watchtower \\ containrrr/watchtower --host \"tcp://10.0.1.2:2375\" or docker run -d \\ --name watchtower \\ -e DOCKER_HOST=\"tcp://10.0.1.2:2375\" \\ containrrr/watchtower Note in both of the examples above that it is unnecessary to mount the /var/run/docker.sock into the watchtower container.","title":"Remote hosts"},{"location":"secure-connections/","text":"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 --tlsverify flag. The docker-machine certificates for a particular host can be located by executing the docker-machine env command for the desired host (note the values for the DOCKER_HOST and DOCKER_CERT_PATH 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 . With the certificates mounted into the watchtower container you need to specify the --tlsverify flag to enable verification of the certificate: docker run -d \\ --name watchtower \\ -e DOCKER_HOST=$DOCKER_HOST \\ -e DOCKER_CERT_PATH=/etc/ssl/docker \\ -v $DOCKER_CERT_PATH:/etc/ssl/docker \\ containrrr/watchtower --tlsverify","title":"Secure connections"},{"location":"stop-signals/","text":"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. This label can be coded directly into your image by using the LABEL instruction in your Dockerfile: LABEL com.centurylinklabs.watchtower.stop-signal=\"SIGHUP\" Or, it can be specified as part of the docker run command line: docker run -d --label=com.centurylinklabs.watchtower.stop-signal=SIGHUP someimage","title":"Stop signals"},{"location":"usage-overview/","text":"Watchtower is itself packaged as a Docker container so installation is as simple as pulling the containrrr/watchtower image. If you are using ARM based architecture, pull the appropriate containrrr/watchtower:armhf-<tag> image from the containrrr Docker Hub . 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 -v flag when you run it. Run the watchtower container with the following command: docker run -d \\ --name watchtower \\ -v /var/run/docker.sock:/var/run/docker.sock \\ containrrr/watchtower If pulling images from private Docker registries, supply registry authentication credentials with the environment variables REPO_USER and REPO_PASS or by mounting the host's docker config file into the container (at the root of the container filesystem / ). Passing environment variables: docker run -d \\ --name watchtower \\ -e REPO_USER=username \\ -e REPO_PASS=password \\ -v /var/run/docker.sock:/var/run/docker.sock \\ containrrr/watchtower container_to_watch --debug Also check out this Stack Overflow answer for more options on how to pass environment variables. Mounting the host's docker config file: docker run -d \\ --name watchtower \\ -v /home/<user>/.docker/config.json:/config.json \\ -v /var/run/docker.sock:/var/run/docker.sock \\ containrrr/watchtower container_to_watch --debug 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 5 minutes. version: \"3\" services: cavo: image: index.docker.io/<org>/<image>:<tag> ports: - \"443:3443\" - \"80:3080\" watchtower: image: containrrr/watchtower volumes: - /var/run/docker.sock:/var/run/docker.sock - /root/.docker/config.json:/config.json command: --interval 30","title":"Usage overview"}]}