diff --git a/docs/arguments.md b/docs/arguments.md index 218680e..4425190 100644 --- a/docs/arguments.md +++ b/docs/arguments.md @@ -258,7 +258,7 @@ Environment Variable: WATCHTOWER_HTTP_API_TOKEN ## HTTP API periodic polls Keep running periodic updates if the HTTP API mode is enabled, otherwise the HTTP API would prevent periodic polls. -``` +```text Argument: --http-api-periodic-polls Environment Variable: WATCHTOWER_HTTP_API_PERIODIC_POLLS Type: Boolean @@ -340,4 +340,4 @@ requests and may rate limit pull requests (mainly docker.io). Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE Possible values: always, auto, never Default: auto -``` \ No newline at end of file +``` diff --git a/docs/container-selection.md b/docs/container-selection.md index 799091f..b5ccafb 100644 --- a/docs/container-selection.md +++ b/docs/container-selection.md @@ -2,8 +2,8 @@ By default, watchtower will watch all containers. However, sometimes only some c There are two options: -- **Fully exclude**: You can choose to exclude containers entirely from being watched by watchtower. -- **Monitor only**: In this mode, watchtower checks for container updates, sends notifications and invokes the [pre-check/post-check hooks](https://containrrr.dev/watchtower/lifecycle-hooks/) on the containers but does **not** perform the update. +- **Fully exclude**: You can choose to exclude containers entirely from being watched by watchtower. +- **Monitor only**: In this mode, watchtower checks for container updates, sends notifications and invokes the [pre-check/post-check hooks](https://containrrr.dev/watchtower/lifecycle-hooks/) on the containers but does **not** perform the update. ## Full Exclude @@ -34,8 +34,8 @@ docker run -d --label=com.centurylinklabs.watchtower.enable=true someimage If you wish to create a monitoring scope, you will need to [run multiple instances and set a scope for each of them](https://containrrr.github.io/watchtower/running-multiple-instances). Watchtower filters running containers by testing them against each configured criteria. A container is monitored if all criteria are met. For example: -- If a container's name is on the monitoring name list (not empty `--name` argument) but it is not enabled (_centurylinklabs.watchtower.enable=false_), it won't be monitored; -- If a container's name is not on the monitoring name list (not empty `--name` argument), even if it is enabled (_centurylinklabs.watchtower.enable=true_ and `--label-enable` flag is set), it won't be monitored; +- If a container's name is on the monitoring name list (not empty `--name` argument) but it is not enabled (_centurylinklabs.watchtower.enable=false_), it won't be monitored; +- If a container's name is not on the monitoring name list (not empty `--name` argument), even if it is enabled (_centurylinklabs.watchtower.enable=true_ and `--label-enable` flag is set), it won't be monitored; ## Monitor Only @@ -54,5 +54,3 @@ docker run -d --label=com.centurylinklabs.watchtower.monitor-only=true someimage ``` When the label is specified on a container, watchtower treats that container exactly as if [`WATCHTOWER_MONITOR_ONLY`](https://containrrr.dev/watchtower/arguments/#without_updating_containers) was set, but the effect is limited to the individual container. - - diff --git a/docs/http-api-mode.md b/docs/http-api-mode.md index 7af1421..2cf082a 100644 --- a/docs/http-api-mode.md +++ b/docs/http-api-mode.md @@ -1,6 +1,6 @@ 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. +- `/v1/update` - triggers an update for all of the containers monitored by this Watchtower instance. --- diff --git a/docs/lifecycle-hooks.md b/docs/lifecycle-hooks.md index cab0485..68dbdae 100644 --- a/docs/lifecycle-hooks.md +++ b/docs/lifecycle-hooks.md @@ -10,10 +10,10 @@ 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. +- 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 diff --git a/docs/metrics.md b/docs/metrics.md index 9741955..2829eac 100644 --- a/docs/metrics.md +++ b/docs/metrics.md @@ -22,4 +22,4 @@ as well as creating a port mapping for your container for port `8080`. The repository contains a demo with prometheus and grafana, available through `docker-compose.yml`. This demo is preconfigured with a dashboard, which will look something like this: -![grafana metrics](assets/grafana-dashboard.png) \ No newline at end of file +![grafana metrics](assets/grafana-dashboard.png) diff --git a/docs/notifications.md b/docs/notifications.md index f783866..c951d29 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -5,11 +5,11 @@ system, [logrus](http://github.com/sirupsen/logrus). The types of notifications 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](https://github.com/containrrr/shoutrrr) +- `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](https://github.com/containrrr/shoutrrr) !!! note "Using multiple notifications with environment variables" There is currently a bug in Viper (https://github.com/spf13/viper/issues/380), which prevents comma-separated slices to @@ -24,9 +24,9 @@ comma-separated list of values to the `--notifications` option ## Settings -- `--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`. -- `--notifications-hostname` (env. `WATCHTOWER_NOTIFICATIONS_HOSTNAME`): Custom hostname specified in subject/title. Useful to override the operating system hostname. -- Watchtower will post a notification every time it is started. This behavior [can be changed](https://containrrr.github.io/watchtower/arguments/#without_sending_a_startup_message) with an argument. +- `--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`. +- `--notifications-hostname` (env. `WATCHTOWER_NOTIFICATIONS_HOSTNAME`): Custom hostname specified in subject/title. Useful to override the operating system hostname. +- Watchtower will post a notification every time it is started. This behavior [can be changed](https://containrrr.github.io/watchtower/arguments/#without_sending_a_startup_message) with an argument. ## Available services @@ -34,15 +34,15 @@ comma-separated list of values to the `--notifications` option 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. Can also reference a file, in which case the contents of the file are used. -- `--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. +- `--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. Can also reference a file, in which case the contents of the file are used. +- `--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: @@ -121,7 +121,7 @@ By default, watchtower will send messages under the name `watchtower`, you can c 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-channel` (env. `WATCHTOWER_NOTIFICATION_SLACK_CHANNEL`): A string which overrides the webhook's default channel. Example: #my-custom-channel. Example: @@ -178,7 +178,7 @@ If you want to disable TLS verification for the Gotify instance, you can use eit 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. +- `--notification-url` (env. `WATCHTOWER_NOTIFICATION_URL`): The shoutrrr service URL to be used. Go to [containrrr.github.io/shoutrrr/services/overview](https://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 @@ -186,7 +186,7 @@ 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. +- `--notification-template` (env. `WATCHTOWER_NOTIFICATION_TEMPLATE`): The template used for the message. The template is a Go [template](https://golang.org/pkg/text/template/) and that format a list of [log entries](https://pkg.go.dev/github.com/sirupsen/logrus?tab=doc#Entry). @@ -198,7 +198,7 @@ outputs timestamp and log level. If you want to adjust the date/time format it must show how the [reference time](https://golang.org/pkg/time/#pkg-constants) (_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. + 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. Example: diff --git a/docs/private-registries.md b/docs/private-registries.md index 354f369..e6edc39 100644 --- a/docs/private-registries.md +++ b/docs/private-registries.md @@ -5,8 +5,8 @@ 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 ` and share the resulting configuration file. +* The configuration file can be created manually. +* Call `docker login ` and share the resulting configuration file. ### Create the configuration file manually Create a new configuration file with the following syntax and a base64 encoded username and @@ -87,7 +87,6 @@ services: - /var/run/docker.sock:/var/run/docker.sock ``` - ## Credential helpers 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. @@ -98,7 +97,6 @@ helper in a separate container and mount it using volumes. ### Example Example implementation for use with [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper): - Use the dockerfile below to build the [amazon-ecr-credential-helper](https://github.com/awslabs/amazon-ecr-credential-helper), in a volume that may be mounted onto your watchtower container. @@ -175,9 +173,12 @@ A few additional notes: 1. With docker-compose the volume (helper, in this case) MUST be set to `external: true`, otherwise docker-compose will preface it with the directory name. + 2. Note that "credsStore" : "ecr-login" is needed - and in theory if you have that you can remove the - credHelpers section + credHelpers section + 3. 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 `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables as well. + 4. 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. diff --git a/docs/remote-hosts.md b/docs/remote-hosts.md index e08fbd3..22c3f94 100644 --- a/docs/remote-hosts.md +++ b/docs/remote-hosts.md @@ -15,4 +15,4 @@ docker run -d \ containrrr/watchtower ``` -Note in both of the examples above that it is unnecessary to mount the _/var/run/docker.sock_ into the watchtower container. \ No newline at end of file +Note in both of the examples above that it is unnecessary to mount the _/var/run/docker.sock_ into the watchtower container. diff --git a/docs/running-multiple-instances.md b/docs/running-multiple-instances.md index 641f4e4..3899095 100644 --- a/docs/running-multiple-instances.md +++ b/docs/running-multiple-instances.md @@ -1,8 +1,8 @@ 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](https://containrrr.github.io/watchtower/arguments/#filter_by_scope) to each running instance. Notice that: -- Multiple instances can't run with the same scope; -- An instance without a scope will clean up other running instances, even if they have a defined scope; +- Multiple instances can't run with the same scope; +- An instance without a scope will clean up other running instances, even if they have a defined scope; To define an instance monitoring scope, use the `--scope` argument or the `WATCHTOWER_SCOPE` environment variable on startup and set the _com.centurylinklabs.watchtower.scope_ label with the same value for the containers you want to include in this instance's scope (including the instance itself). @@ -24,4 +24,4 @@ services: command: --interval 30 --scope myscope labels: - "com.centurylinklabs.watchtower.scope=myscope" -``` \ No newline at end of file +```