--host
$ docker run -d \ - --name watchtower \ - -v /var/run/docker.sock:/var/run/docker.sock \ - containrrr/watchtower \ - nginx redis +$ 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 +$ 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. +Secrets/Files¶ +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. +The following arguments are currently supported (including their corresponding WATCHTOWER_ environment variables): + - notification-url + - notification-email-server-password + - notification-slack-hook-url + - notification-msteams-hook + - notification-gotify-token + - http-api-token +Example docker-compose usage¶ +secrets: + access_token: + file: access_token + +services: + watchtower: + secrets: + - access_token + environment: + - WATCHTOWER_HTTP_API_TOKEN=/run/secrets/access_token + Help¶ Shows documentation about the supported flags. Argument: --help @@ -988,8 +1206,8 @@ Environment Variable: WATCHTOWER_CLEANUP Type: Boolean Default: false -Remove attached volumes¶ -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. +Remove anonymous volumes¶ +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! Argument: --remove-volumes Environment Variable: WATCHTOWER_REMOVE_VOLUMES Type: Boolean @@ -1026,6 +1244,13 @@ Environment Variable: WATCHTOWER_LOG_LEVEL Possible values: panic, fatal, error, warn, info, debug or trace Default: info +Logging format¶ +Sets what logging format to use for console output. + Argument: --log-format, -l +Environment Variable: WATCHTOWER_LOG_FORMAT + Possible values: Auto, LogFmt, Pretty or JSON + Default: Auto + ANSI colors¶ Disable ANSI color escape codes in log output. Argument: --no-color @@ -1056,7 +1281,7 @@ Environment Variable: WATCHTOWER_INCLUDE_RESTARTING Include stopped¶ Will also include created and exited containers. - Argument: --include-stopped + Argument: --include-stopped, -S Environment Variable: WATCHTOWER_INCLUDE_STOPPED Type: Boolean Default: false @@ -1076,14 +1301,14 @@ Environment Variable: WATCHTOWER_POLL_INTERVAL Default: 86400 (24 hours) Filter by enable label¶ -Update containers that have a com.centurylinklabs.watchtower.enable label set to true. +Monitor and 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¶ -Do not update containers that have com.centurylinklabs.watchtower.enable label set to false and +Do not Monitor and 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¶ @@ -1102,6 +1327,14 @@ Environment Variable: WATCHTOWER_MONITOR_ONLY Default: false Note that monitor-only can also be specified on a per-container basis with the com.centurylinklabs.watchtower.monitor-only label set on those containers. +See With label taking precedence over arguments for behavior when both argument and label are set +With label taking precedence over arguments¶ +By default, arguments will take precedence over labels. This means that if you set WATCHTOWER_MONITOR_ONLY to true or use --monitor-only, a container with com.centurylinklabs.watchtower.monitor-only set to false will not be updated. If you set WATCHTOWER_LABEL_TAKE_PRECEDENCE to true or use --label-take-precedence, then the container will also be updated. This also apply to the no pull option. if you set WATCHTOWER_NO_PULL to true or use --no-pull, a container with com.centurylinklabs.watchtower.no-pull set to false will not pull the new image. If you set WATCHTOWER_LABEL_TAKE_PRECEDENCE to true or use --label-take-precedence, then the container will pull image + Argument: --label-take-precedence +Environment Variable: WATCHTOWER_LABEL_TAKE_PRECEDENCE + Type: Boolean + Default: false + Without restarting containers¶ 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. @@ -1120,6 +1353,9 @@ Environment Variable: WATCHTOWER_NO_PULL Type: Boolean Default: false +Note that no-pull can also be specified on a per-container basis with the +com.centurylinklabs.watchtower.no-pull label set on those containers. +See With label taking precedence over arguments for behavior when both argument and label are set Without sending a startup message¶ Do not send a message after watchtower started. Otherwise there will be an info-level notification. Argument: --no-startup-message @@ -1129,7 +1365,7 @@ Environment Variable: WATCHTOWER_NO_STARTUP_MESSAGE Run once¶ Run an update attempt against a container name list one time immediately and exit. - Argument: --run-once + Argument: --run-once, -R Environment Variable: WATCHTOWER_RUN_ONCE Type: Boolean Default: false @@ -1143,7 +1379,8 @@ Environment Variable: WATCHTOWER_HTTP_API_UPDATE Default: false HTTP API Token¶ -Sets an authentication token to HTTP API requests. +Sets an authentication token to HTTP API requests. +Can also reference a file, in which case the contents of the file are used. Argument: --http-api-token Environment Variable: WATCHTOWER_HTTP_API_TOKEN Type: String @@ -1210,6 +1447,27 @@ Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE Possible values: always, auto, never Default: auto +Health check¶ +Returns a success exit code to enable usage with docker HEALTHCHECK. 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. + +Only for HEALTHCHECK use +Never put this on the main container executable command line as it is only meant to be run from docker HEALTHCHECK. + + Argument: --health-check + +Programatic Output (porcelain)¶ +Writes the session results to STDOUT using a stable, machine-readable format (indicated by the argument VERSION). +Alias for: + --notification-url logger:// + --notification-log-stdout + --notification-report + --notification-template porcelain.VERSION.summary-no-log + + Argument: --porcelain, -P +Environment Variable: WATCHTOWER_PORCELAIN + Possible values: v1 + Default: - + @@ -1226,42 +1484,6 @@ Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE
$ 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.
--run-once
$ docker run --rm \ - -v /var/run/docker.sock:/var/run/docker.sock \ - containrrr/watchtower \ - --run-once \ - nginx redis +$ 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. +Secrets/Files¶ +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. +The following arguments are currently supported (including their corresponding WATCHTOWER_ environment variables): + - notification-url + - notification-email-server-password + - notification-slack-hook-url + - notification-msteams-hook + - notification-gotify-token + - http-api-token +Example docker-compose usage¶ +secrets: + access_token: + file: access_token + +services: + watchtower: + secrets: + - access_token + environment: + - WATCHTOWER_HTTP_API_TOKEN=/run/secrets/access_token + Help¶ Shows documentation about the supported flags. Argument: --help @@ -988,8 +1206,8 @@ Environment Variable: WATCHTOWER_CLEANUP Type: Boolean Default: false -Remove attached volumes¶ -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. +Remove anonymous volumes¶ +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! Argument: --remove-volumes Environment Variable: WATCHTOWER_REMOVE_VOLUMES Type: Boolean @@ -1026,6 +1244,13 @@ Environment Variable: WATCHTOWER_LOG_LEVEL Possible values: panic, fatal, error, warn, info, debug or trace Default: info +Logging format¶ +Sets what logging format to use for console output. + Argument: --log-format, -l +Environment Variable: WATCHTOWER_LOG_FORMAT + Possible values: Auto, LogFmt, Pretty or JSON + Default: Auto + ANSI colors¶ Disable ANSI color escape codes in log output. Argument: --no-color @@ -1056,7 +1281,7 @@ Environment Variable: WATCHTOWER_INCLUDE_RESTARTING Include stopped¶ Will also include created and exited containers. - Argument: --include-stopped + Argument: --include-stopped, -S Environment Variable: WATCHTOWER_INCLUDE_STOPPED Type: Boolean Default: false @@ -1076,14 +1301,14 @@ Environment Variable: WATCHTOWER_POLL_INTERVAL Default: 86400 (24 hours) Filter by enable label¶ -Update containers that have a com.centurylinklabs.watchtower.enable label set to true. +Monitor and 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¶ -Do not update containers that have com.centurylinklabs.watchtower.enable label set to false and +Do not Monitor and 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¶ @@ -1102,6 +1327,14 @@ Environment Variable: WATCHTOWER_MONITOR_ONLY Default: false Note that monitor-only can also be specified on a per-container basis with the com.centurylinklabs.watchtower.monitor-only label set on those containers. +See With label taking precedence over arguments for behavior when both argument and label are set +With label taking precedence over arguments¶ +By default, arguments will take precedence over labels. This means that if you set WATCHTOWER_MONITOR_ONLY to true or use --monitor-only, a container with com.centurylinklabs.watchtower.monitor-only set to false will not be updated. If you set WATCHTOWER_LABEL_TAKE_PRECEDENCE to true or use --label-take-precedence, then the container will also be updated. This also apply to the no pull option. if you set WATCHTOWER_NO_PULL to true or use --no-pull, a container with com.centurylinklabs.watchtower.no-pull set to false will not pull the new image. If you set WATCHTOWER_LABEL_TAKE_PRECEDENCE to true or use --label-take-precedence, then the container will pull image + Argument: --label-take-precedence +Environment Variable: WATCHTOWER_LABEL_TAKE_PRECEDENCE + Type: Boolean + Default: false + Without restarting containers¶ 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. @@ -1120,6 +1353,9 @@ Environment Variable: WATCHTOWER_NO_PULL Type: Boolean Default: false
$ 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.
--rm
When no arguments are specified, watchtower will monitor all running containers.
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.
The following arguments are currently supported (including their corresponding WATCHTOWER_ environment variables): + - notification-url + - notification-email-server-password + - notification-slack-hook-url + - notification-msteams-hook + - notification-gotify-token + - http-api-token
WATCHTOWER_
notification-url
notification-email-server-password
notification-slack-hook-url
notification-msteams-hook
notification-gotify-token
http-api-token
secrets: + access_token: + file: access_token + +services: + watchtower: + secrets: + - access_token + environment: + - WATCHTOWER_HTTP_API_TOKEN=/run/secrets/access_token +
Shows documentation about the supported flags.
Argument: --help @@ -988,8 +1206,8 @@ Environment Variable: WATCHTOWER_CLEANUP Type: Boolean Default: false
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.
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!
Argument: --remove-volumes Environment Variable: WATCHTOWER_REMOVE_VOLUMES Type: Boolean @@ -1026,6 +1244,13 @@ Environment Variable: WATCHTOWER_LOG_LEVEL Possible values: panic, fatal, error, warn, info, debug or trace Default: info
Sets what logging format to use for console output.
Argument: --log-format, -l +Environment Variable: WATCHTOWER_LOG_FORMAT + Possible values: Auto, LogFmt, Pretty or JSON + Default: Auto +
Disable ANSI color escape codes in log output.
Argument: --no-color @@ -1056,7 +1281,7 @@ Environment Variable: WATCHTOWER_INCLUDE_RESTARTING
Will also include created and exited containers.
Argument: --include-stopped + Argument: --include-stopped, -S Environment Variable: WATCHTOWER_INCLUDE_STOPPED Type: Boolean Default: false @@ -1076,14 +1301,14 @@ Environment Variable: WATCHTOWER_POLL_INTERVAL Default: 86400 (24 hours) Filter by enable label¶ -Update containers that have a com.centurylinklabs.watchtower.enable label set to true. +Monitor and 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¶ -Do not update containers that have com.centurylinklabs.watchtower.enable label set to false and +Do not Monitor and 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¶ @@ -1102,6 +1327,14 @@ Environment Variable: WATCHTOWER_MONITOR_ONLY Default: false
Argument: --include-stopped, -S Environment Variable: WATCHTOWER_INCLUDE_STOPPED Type: Boolean Default: false @@ -1076,14 +1301,14 @@ Environment Variable: WATCHTOWER_POLL_INTERVAL Default: 86400 (24 hours)
Update containers that have a com.centurylinklabs.watchtower.enable label set to true.
com.centurylinklabs.watchtower.enable
Monitor and 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
Do not update containers that have com.centurylinklabs.watchtower.enable label set to false and +
Do not Monitor and 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.
--label-enable
Note that monitor-only can also be specified on a per-container basis with the com.centurylinklabs.watchtower.monitor-only label set on those containers.
com.centurylinklabs.watchtower.monitor-only
See With label taking precedence over arguments for behavior when both argument and label are set
By default, arguments will take precedence over labels. This means that if you set WATCHTOWER_MONITOR_ONLY to true or use --monitor-only, a container with com.centurylinklabs.watchtower.monitor-only set to false will not be updated. If you set WATCHTOWER_LABEL_TAKE_PRECEDENCE to true or use --label-take-precedence, then the container will also be updated. This also apply to the no pull option. if you set WATCHTOWER_NO_PULL to true or use --no-pull, a container with com.centurylinklabs.watchtower.no-pull set to false will not pull the new image. If you set WATCHTOWER_LABEL_TAKE_PRECEDENCE to true or use --label-take-precedence, then the container will pull image
WATCHTOWER_MONITOR_ONLY
--monitor-only
WATCHTOWER_LABEL_TAKE_PRECEDENCE
--label-take-precedence
WATCHTOWER_NO_PULL
--no-pull
com.centurylinklabs.watchtower.no-pull
Argument: --label-take-precedence +Environment Variable: WATCHTOWER_LABEL_TAKE_PRECEDENCE + Type: Boolean + Default: false +
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. @@ -1120,6 +1353,9 @@ Environment Variable: WATCHTOWER_NO_PULL Type: Boolean Default: false
Note that no-pull can also be specified on a per-container basis with the +com.centurylinklabs.watchtower.no-pull label set on those containers.
Do not send a message after watchtower started. Otherwise there will be an info-level notification.
Argument: --no-startup-message @@ -1129,7 +1365,7 @@ Environment Variable: WATCHTOWER_NO_STARTUP_MESSAGE
Run an update attempt against a container name list one time immediately and exit.
Argument: --run-once + Argument: --run-once, -R Environment Variable: WATCHTOWER_RUN_ONCE Type: Boolean Default: false @@ -1143,7 +1379,8 @@ Environment Variable: WATCHTOWER_HTTP_API_UPDATE Default: false HTTP API Token¶ -Sets an authentication token to HTTP API requests. +Sets an authentication token to HTTP API requests. +Can also reference a file, in which case the contents of the file are used. Argument: --http-api-token Environment Variable: WATCHTOWER_HTTP_API_TOKEN Type: String @@ -1210,6 +1447,27 @@ Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE Possible values: always, auto, never Default: auto +Health check¶ +Returns a success exit code to enable usage with docker HEALTHCHECK. 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. + +Only for HEALTHCHECK use +Never put this on the main container executable command line as it is only meant to be run from docker HEALTHCHECK. + + Argument: --health-check + +Programatic Output (porcelain)¶ +Writes the session results to STDOUT using a stable, machine-readable format (indicated by the argument VERSION). +Alias for: + --notification-url logger:// + --notification-log-stdout + --notification-report + --notification-template porcelain.VERSION.summary-no-log + + Argument: --porcelain, -P +Environment Variable: WATCHTOWER_PORCELAIN + Possible values: v1 + Default: - + @@ -1226,42 +1484,6 @@ Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE
Argument: --run-once, -R Environment Variable: WATCHTOWER_RUN_ONCE Type: Boolean Default: false @@ -1143,7 +1379,8 @@ Environment Variable: WATCHTOWER_HTTP_API_UPDATE Default: false
Sets an authentication token to HTTP API requests.
Sets an authentication token to HTTP API requests. +Can also reference a file, in which case the contents of the file are used.
Argument: --http-api-token Environment Variable: WATCHTOWER_HTTP_API_TOKEN Type: String @@ -1210,6 +1447,27 @@ Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE Possible values: always, auto, never Default: auto
Returns a success exit code to enable usage with docker HEALTHCHECK. 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.
HEALTHCHECK
Only for HEALTHCHECK use
Never put this on the main container executable command line as it is only meant to be run from docker HEALTHCHECK.
Argument: --health-check +
Writes the session results to STDOUT using a stable, machine-readable format (indicated by the argument VERSION).
Alias for:
--notification-url logger:// + --notification-log-stdout + --notification-report + --notification-template porcelain.VERSION.summary-no-log + + Argument: --porcelain, -P +Environment Variable: WATCHTOWER_PORCELAIN + Possible values: v1 + Default: - +