diff --git a/README.md b/README.md index 0d9d512..5d1f08a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@

[![Circle CI](https://circleci.com/gh/containrrr/watchtower.svg?style=shield)](https://circleci.com/gh/containrrr/watchtower) - [![codecov](https://codecov.io/gh/containrrr/watchtower/branch/master/graph/badge.svg?token=8pxWgB380Y)](https://codecov.io/gh/containrrr/watchtower) + [![codecov](https://codecov.io/gh/containrrr/watchtower/branch/main/graph/badge.svg)](https://codecov.io/gh/containrrr/watchtower) [![GoDoc](https://godoc.org/github.com/containrrr/watchtower?status.svg)](https://godoc.org/github.com/containrrr/watchtower) [![Microbadger](https://images.microbadger.com/badges/image/containrrr/watchtower.svg)](https://microbadger.com/images/containrrr/watchtower) [![Go Report Card](https://goreportcard.com/badge/github.com/containrrr/watchtower)](https://goreportcard.com/report/github.com/containrrr/watchtower) diff --git a/docs/arguments.md b/docs/arguments.md index 70efc21..4763940 100644 --- a/docs/arguments.md +++ b/docs/arguments.md @@ -30,7 +30,7 @@ When no arguments are specified, watchtower will monitor all running containers. ## Help Shows documentation about the supported flags. -``` +```text Argument: --help Environment Variable: N/A Type: N/A @@ -41,7 +41,7 @@ Environment Variable: N/A 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), find your location and use the value in _TZ Database Name_, e.g _Europe/Rome_. The timezone can alternatively be set by volume mounting your hosts /etc/localtime file. `-v /etc/localtime:/etc/localtime:ro` -``` +```text Argument: N/A Environment Variable: TZ Type: String @@ -51,7 +51,7 @@ Environment Variable: TZ ## Cleanup 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. -``` +```text Argument: --cleanup Environment Variable: WATCHTOWER_CLEANUP Type: Boolean @@ -61,7 +61,7 @@ Environment Variable: WATCHTOWER_CLEANUP ## 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. -``` +```text Argument: --remove-volumes Environment Variable: WATCHTOWER_REMOVE_VOLUMES Type: Boolean @@ -71,7 +71,7 @@ Environment Variable: WATCHTOWER_REMOVE_VOLUMES ## Debug Enable debug mode with verbose logging. -``` +```text Argument: --debug, -d Environment Variable: WATCHTOWER_DEBUG Type: Boolean @@ -81,7 +81,7 @@ Environment Variable: WATCHTOWER_DEBUG ## Trace Enable trace mode with very verbose logging. Caution: exposes credentials! -``` +```text Argument: --trace Environment Variable: WATCHTOWER_TRACE Type: Boolean @@ -91,7 +91,7 @@ Environment Variable: WATCHTOWER_TRACE ## ANSI colors Disable ANSI color escape codes in log output. -``` +```text Argument: --no-color Environment Variable: NO_COLOR Type: Boolean @@ -101,7 +101,7 @@ Environment Variable: NO_COLOR ## Docker host Docker daemon socket to connect to. Can be pointed at a remote Docker host by specifying a TCP endpoint as "tcp://hostname:port". -``` +```text Argument: --host, -H Environment Variable: DOCKER_HOST Type: String @@ -111,7 +111,7 @@ Environment Variable: DOCKER_HOST ## Docker API version The API version to use by the Docker client for connecting to the Docker daemon. The minimum supported version is 1.24. -``` +```text Argument: --api-version, -a Environment Variable: DOCKER_API_VERSION Type: String @@ -121,7 +121,7 @@ Environment Variable: DOCKER_API_VERSION ## Include restarting Will also include restarting containers. -``` +```text Argument: --include-restarting Environment Variable: WATCHTOWER_INCLUDE_RESTARTING Type: Boolean @@ -131,7 +131,7 @@ Environment Variable: WATCHTOWER_INCLUDE_RESTARTING ## Include stopped Will also include created and exited containers. -``` +```text Argument: --include-stopped Environment Variable: WATCHTOWER_INCLUDE_STOPPED Type: Boolean @@ -141,7 +141,7 @@ Environment Variable: WATCHTOWER_INCLUDE_STOPPED ## Revive stopped Start any stopped containers that have had their image updated. This argument is only usable with the `--include-stopped` argument. -``` +```text Argument: --revive-stopped Environment Variable: WATCHTOWER_REVIVE_STOPPED Type: Boolean @@ -151,7 +151,7 @@ Environment Variable: WATCHTOWER_REVIVE_STOPPED ## Poll interval 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. -``` +```text Argument: --interval, -i Environment Variable: WATCHTOWER_POLL_INTERVAL Type: Integer @@ -161,7 +161,7 @@ Environment Variable: WATCHTOWER_POLL_INTERVAL ## Filter by enable label Update containers that have a `com.centurylinklabs.watchtower.enable` label set to true. -``` +```text Argument: --label-enable Environment Variable: WATCHTOWER_LABEL_ENABLE Type: Boolean @@ -169,16 +169,20 @@ Environment Variable: WATCHTOWER_LABEL_ENABLE ``` ## Filter by disable label -**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. +__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 -Will only monitor for new images, send notifications and invoke the [pre-check/post-check hooks](https://containrrr.dev/watchtower/lifecycle-hooks/), but will **not** update the containers. +Will only monitor for new images, send notifications and invoke +the [pre-check/post-check hooks](https://containrrr.dev/watchtower/lifecycle-hooks/), but will __not__ update the +containers. -> **⚠️ Please note** -> -> Due to Docker API limitations the latest image will still be pulled from the registry. +!!! note Due to Docker API limitations the latest image will still be pulled from the registry. +The HEAD digest checks allows watchtower to skip pulling when there are no changes, but to know _what_ has changed it +will still do a pull whenever the repository digest doesn't match the local image digest. -``` +```text Argument: --monitor-only Environment Variable: WATCHTOWER_MONITOR_ONLY Type: Boolean @@ -190,7 +194,7 @@ Note that monitor-only can also be specified on a per-container basis with the ` ## 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. -``` +```text Argument: --no-restart Environment Variable: WATCHTOWER_NO_RESTART Type: Boolean @@ -203,7 +207,7 @@ new images from the registry. Instead it will only monitor the local image cache Use this option if you are building new images directly on the Docker host without pushing them to a registry. -``` +```text Argument: --no-pull Environment Variable: WATCHTOWER_NO_PULL Type: Boolean @@ -213,7 +217,7 @@ Environment Variable: WATCHTOWER_NO_PULL ## Without sending a startup message Do not send a message after watchtower started. Otherwise there will be an info-level notification. -``` +```text Argument: --no-startup-message Environment Variable: WATCHTOWER_NO_STARTUP_MESSAGE Type: Boolean @@ -223,7 +227,7 @@ Environment Variable: WATCHTOWER_NO_STARTUP_MESSAGE ## Run once Run an update attempt against a container name list one time immediately and exit. -``` +```text Argument: --run-once Environment Variable: WATCHTOWER_RUN_ONCE Type: Boolean @@ -231,9 +235,10 @@ Environment Variable: WATCHTOWER_RUN_ONCE ``` ## HTTP API Mode -Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. For details see [HTTP API](https://containrrr.github.io/watchtower/http-api-mode). +Runs Watchtower in HTTP API mode, only allowing image updates to be triggered by an HTTP request. +For details see [HTTP API](https://containrrr.github.io/watchtower/http-api-mode). -``` +```text Argument: --http-api-update Environment Variable: WATCHTOWER_HTTP_API Type: Boolean @@ -243,7 +248,7 @@ Environment Variable: WATCHTOWER_HTTP_API ## HTTP API Token Sets an authentication token to HTTP API requests. -``` +```text Argument: --http-api-token Environment Variable: WATCHTOWER_HTTP_API_TOKEN Type: String @@ -251,9 +256,10 @@ Environment Variable: WATCHTOWER_HTTP_API_TOKEN ``` ## Filter by scope -Update containers that have a `com.centurylinklabs.watchtower.scope` label set with the same value as the given argument. This enables [running multiple instances](https://containrrr.github.io/watchtower/running-multiple-instances). +Update containers that have a `com.centurylinklabs.watchtower.scope` label set with the same value as the given argument. +This enables [running multiple instances](https://containrrr.github.io/watchtower/running-multiple-instances). -``` +```text Argument: --scope Environment Variable: WATCHTOWER_SCOPE Type: String @@ -263,7 +269,7 @@ Environment Variable: WATCHTOWER_SCOPE ## HTTP API Metrics Enables a metrics endpoint, exposing prometheus metrics via HTTP. See [Metrics](metrics.md) for details. -``` +```text Argument: --http-api-metrics Environment Variable: WATCHTOWER_HTTP_API_METRICS Type: Boolean @@ -274,7 +280,7 @@ Environment Variable: WATCHTOWER_HTTP_API_METRICS [Cron expression](https://pkg.go.dev/github.com/robfig/cron@v1.2.0?tab=doc#hdr-CRON_Expression_Format) 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 * * *"` -``` +```text Argument: --schedule, -s Environment Variable: WATCHTOWER_SCHEDULE Type: String @@ -285,7 +291,7 @@ Environment Variable: WATCHTOWER_SCHEDULE Restart one image at time instead of stopping and starting all at once. Useful in conjunction with lifecycle hooks to implement zero-downtime deploy. -``` +```text Argument: --rolling-restart Environment Variable: WATCHTOWER_ROLLING_RESTART Type: Boolean @@ -295,7 +301,7 @@ Environment Variable: WATCHTOWER_ROLLING_RESTART ## Wait until timeout 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. -``` +```text Argument: --stop-timeout Environment Variable: WATCHTOWER_TIMEOUT Type: Duration @@ -303,11 +309,25 @@ Environment Variable: WATCHTOWER_TIMEOUT ``` ## TLS Verification -Use TLS when connecting to the Docker socket and verify the server's certificate. See below for options used to configure notifications. -``` +Use TLS when connecting to the Docker socket and verify the server's certificate. See below for options used to +configure notifications. + +```text Argument: --tlsverify Environment Variable: DOCKER_TLS_VERIFY Type: Boolean Default: false ``` + +## HEAD failure warnings + +When to warn about HEAD pull requests failing. Auto means that it will warn when the registry is known to handle the +requests and may rate limit pull requests (mainly docker.io). + +```text + Argument: --warn-on-head-failure +Environment Variable: WATCHTOWER_WARN_ON_HEAD_FAILURE + Possible values: always, auto, never + Default: auto +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index e999c03..9d52da3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ Circle CI - Codecov + Codecov GoDoc @@ -42,11 +42,21 @@ ## Quick Start -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: +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" +```bash $ docker run -d \ +--name watchtower \ +-v /var/run/docker.sock:/var/run/docker.sock \ +containrrr/watchtower ``` -$ docker run -d \ - --name watchtower \ - -v /var/run/docker.sock:/var/run/docker.sock \ - containrrr/watchtower -``` +=== "docker-compose.yml" +```yaml version: "3" +services: +watchtower: +image: containrrr/watchtower volumes: +- /var/run/docker.sock:/var/run/docker.sock +``` \ No newline at end of file diff --git a/docs/introduction.md b/docs/introduction.md index 9e0f5fe..ded074f 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -4,7 +4,7 @@ With watchtower you can update the running version of your containerized app sim For example, let's say you were running watchtower along with an instance of _centurylink/wetty-cli_ image: -```bash +```text $ docker ps CONTAINER ID IMAGE STATUS PORTS NAMES 967848166a45 centurylink/wetty-cli Up 10 minutes 0.0.0.0:8080->3000/tcp wetty diff --git a/docs/lifecycle-hooks.md b/docs/lifecycle-hooks.md index f8bc640..df30695 100644 --- a/docs/lifecycle-hooks.md +++ b/docs/lifecycle-hooks.md @@ -1,7 +1,8 @@ ## Executing commands before and after updating -> **DO NOTE**: These are shell commands executed with `sh`, and therefore require the -> container to provide the `sh` executable. +!!! 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. @@ -26,24 +27,21 @@ The commands are specified using docker container labels, the following are curr | 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): +These labels can be declared as instructions in a Dockerfile (with some example .sh files) or be specified as part of +the `docker run` command line: -```docker -LABEL com.centurylinklabs.watchtower.lifecycle.pre-check="/sync.sh" +=== "Dockerfile" +```docker 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: - -```bash -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" \ +=== "docker run" +```bash 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 diff --git a/docs/metrics.md b/docs/metrics.md index d8ea1b4..9741955 100644 --- a/docs/metrics.md +++ b/docs/metrics.md @@ -1,7 +1,6 @@ -> **⚠️ Experimental feature** -> -> This feature was added in v1.0.4 and is still considered experimental. -> If you notice any strange behavior, please raise a ticket in the repository issues. +!!! warning "Experimental feature" + This feature was added in v1.0.4 and is still considered experimental. If you notice any strange behavior, please raise + a ticket in the repository issues. Metrics can be used to track how Watchtower behaves over time. diff --git a/docs/notifications.md b/docs/notifications.md index 57603cb..5a5feb2 100644 --- a/docs/notifications.md +++ b/docs/notifications.md @@ -1,7 +1,9 @@ # Notifications -Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging system, [logrus](http://github.com/sirupsen/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: +Watchtower can send notifications when containers are updated. Notifications are sent via hooks in the logging +system, [logrus](http://github.com/sirupsen/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 @@ -9,11 +11,16 @@ The types of notifications to send are set by passing a comma-separated list of - `gotify` to send notifications via Gotify - `shoutrrr` to send notifications via [containrrr/shoutrrr](https://github.com/containrrr/shoutrrr) -> There is currently a [bug](https://github.com/spf13/viper/issues/380) 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. +!!! 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 + 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: + ``` + 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 @@ -60,7 +67,6 @@ The following example assumes, that your domain is called `your-domain.com` and Example including an SMTP relay: ```yaml ---- version: '3.8' services: watchtower: @@ -117,8 +123,6 @@ 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-icon-emoji` (env. `WATCHTOWER_NOTIFICATION_SLACK_ICON_EMOJI`): An [emoji code](https://www.webpagefx.com/tools/emoji-cheat-sheet/) 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: @@ -130,8 +134,6 @@ docker run -d \ -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= \ containrrr/watchtower ``` @@ -179,16 +181,25 @@ To send notifications via shoutrrr, the following command-line options, or their - `--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 URLs. (See example below) +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 +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](https://golang.org/pkg/text/template/) and the you format a list of [log entries](https://pkg.go.dev/github.com/sirupsen/logrus?tab=doc#Entry). +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). + +The default value if not set is `{{range .}}{{.Message}}{{println}}{{end}}`. The example below uses a template that also +outputs timestamp and log level. -The default value if not set is `{{range .}}{{.Message}}{{println}}{{end}}`. The example below uses a template that also outputs timestamp and log level. +!!! tip "Custom date format" + 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. Example: diff --git a/docs/private-registries.md b/docs/private-registries.md index 535b3e8..f35252e 100644 --- a/docs/private-registries.md +++ b/docs/private-registries.md @@ -26,17 +26,17 @@ password `auth` string: (e.g., `my-private-registry.example.org`) The required `auth` string can be generated as follows: + ```bash echo -n 'username:password' | base64 ``` -> ### ℹ️ Username and Password for GCloud -> -> For gcloud, we'll use `_json_key` as our username and the content -> of `gcloudauth.json` as the password. ->```bash -> echo -n "_json_key:$(cat gcloudauth.json)" | base64 -w0 ->``` +!!! info "Username and Password for GCloud" + For gcloud, we'll use `_json_key` as our username and the content of `gcloudauth.json` as the password. + ``` + bash echo -n "_json_key:$(cat gcloudauth.json)" | base64 -w0 + ``` + When the watchtower Docker container is started, the created configuration file (`/config.json` in this example) needs to be passed to the container: @@ -45,6 +45,7 @@ docker run [...] -v /config.json:/config.json containrrr/watchtower ``` ### Share the Docker configuration file + 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 `/.docker/config.json`. This configuration file can be directly used by watchtower. In this case, the creation of an @@ -101,79 +102,78 @@ Example implementation for use with [amazon-ecr-credential-helper](https://githu 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. -1. Create the Dockerfile (contents below): - -```Dockerfile -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/ -``` +1. Create the Dockerfile (contents below): + + ```Dockerfile + 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/ + ``` 2. Use the following commands to build the aws-ecr-dock-cred-helper and store it's output in a volume: -```shell script -# Create a volume to store the command (once built) -docker volume create helper - -# Build the container -docker build -t aws-ecr-dock-cred-helper . - -# Build the command and store it in the new volume in the /go/bin directory. -docker run -d --rm --name aws-cred-helper --volume helper:/go/bin aws-ecr-dock-cred-helper - -``` + ```bash + # Create a volume to store the command (once built) + docker volume create helper + + # Build the container + docker build -t aws-ecr-dock-cred-helper . + + # Build the command and store it in the new volume in the /go/bin directory. + docker run -d --rm --name aws-cred-helper --volume helper:/go/bin aws-ecr-dock-cred-helper + + ``` 3. Create a configuration file for docker, and store it in $HOME/.docker/config.json (replace the - placeholders with your AWS Account ID): - -```json -{ - "credsStore" : "ecr-login", - "HttpHeaders" : { - "User-Agent" : "Docker-Client/19.03.1 (XXXXXX)" - }, - "auths" : { - ".dkr.ecr.us-west-1.amazonaws.com" : {} - }, - "credHelpers": { - ".dkr.ecr.us-west-1.amazonaws.com" : "ecr-login" - } -} -``` + placeholders with your AWS Account ID): + + ```json + { + "credsStore" : "ecr-login", + "HttpHeaders" : { + "User-Agent" : "Docker-Client/19.03.1 (XXXXXX)" + }, + "auths" : { + ".dkr.ecr.us-west-1.amazonaws.com" : {} + }, + "credHelpers": { + ".dkr.ecr.us-west-1.amazonaws.com" : "ecr-login" + } + } + ``` 4. Create a docker-compose file (as an example) to help launch the container: - -and the docker-compose definition: -```yaml -version: "3.4" -services: - # Check for new images and restart things if a new image exists - # for any of our containers. - watchtower: - image: containrrr/watchtower:latest + + ```yaml + version: "3.4" + services: + # Check for new images and restart things if a new image exists + # for any of our containers. + watchtower: + image: containrrr/watchtower:latest + volumes: + - /var/run/docker.sock:/var/run/docker.sock + - .docker/config.json:/config.json + - helper:/go/bin + environment: + - HOME=/ + - PATH=$PATH:/go/bin + - AWS_REGION=us-west-1 volumes: - - /var/run/docker.sock:/var/run/docker.sock - - .docker/config.json:/config.json - - helper:/go/bin - environment: - - HOME=/ - - PATH=$PATH:/go/bin - - AWS_REGION=us-west-1 -volumes: - helper: - external: true -``` + helper: + external: true + ``` A few additional notes: diff --git a/docs/usage-overview.md b/docs/usage-overview.md index 04178a4..1462ba6 100644 --- a/docs/usage-overview.md +++ b/docs/usage-overview.md @@ -37,9 +37,19 @@ docker run -d \ containrrr/watchtower container_to_watch --debug ``` -> NOTE: if you mount `config.json` in the manner above, changes from the host system will (generally) not be propagated to the running container. Mounting files into the Docker daemon uses bind mounts, which are based on inodes. Most applications (including `docker login` and `vim`) will not directly edit the file, but instead make a copy and replace the original file, which results in a new inode which in turn *breaks* the bind mount. **As a workaround**, you can create a symlink to your `config.json` file and then mount the symlink in the container. The symlinked file will always have the same inode, which keeps the bind mount intact and will ensure changes to the original file are propagated to the running container (regardless of the inode of the source file!). +!!! note "Changes to config.json while running" + If you mount `config.json` in the manner above, changes from the host system will (generally) not be propagated to the + running container. Mounting files into the Docker daemon uses bind mounts, which are based on inodes. Most + applications (including `docker login` and `vim`) will not directly edit the file, but instead make a copy and replace + the original file, which results in a new inode which in turn _breaks_ the bind mount. + **As a workaround**, you can create a symlink to your `config.json` file and then mount the symlink in the container. + The symlinked file will always have the same inode, which keeps the bind mount intact and will ensure changes + to the original file are propagated to the running container (regardless of the inode of the source file!). -If you mount the config file as described above, be sure to also prepend the URL for the registry when starting up your watched image (you can omit the https://). Here is a complete docker-compose.yml file that starts up a docker container from a private repo at Docker Hub and monitors it with watchtower. Note the command argument changing the interval to 30s rather than the default 24 hours. +If you mount the config file as described above, be sure to also prepend the URL for the registry when starting up your +watched image (you can omit the https://). Here is a complete docker-compose.yml file that starts up a docker container +from a private repo at Docker Hub and monitors it with watchtower. Note the command argument changing the interval to +30s rather than the default 24 hours. ```yaml version: "3" diff --git a/mkdocs.yml b/mkdocs.yml index 67529aa..46a941c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: Watchtower -site_url: http://containrrr.github.io/watchtower/ +site_url: https://containrrr.dev/watchtower/ repo_url: https://github.com/containrrr/watchtower/ edit_uri: edit/main/docs/ theme: @@ -14,7 +14,16 @@ markdown_extensions: - toc: permalink: True separator: "_" - - codehilite + - admonition + - pymdownx.highlight + - pymdownx.superfences + - pymdownx.magiclink: + repo_url_shortener: True + provider: github + user: containrrr + repo: watchtower + - pymdownx.saneheaders + - pymdownx.tabbed nav: - 'Home': 'index.md' - 'Introduction': 'introduction.md'