Skip to content

Commit

Permalink
Documentation updates (#936)
Browse files Browse the repository at this point in the history 
* Update private-registries.md

* docs: fix codecov branch

* docs: clarify monitor and add head fail warning

* docs: remove unsupported features

* docs: add date format note and fix typo

* docs: 🌈

* docs: fix auto-format errors and linting

* docs: fix auto-format errors and linting
  • Loading branch information
@piksel
piksel authored Apr 27, 2021
1 parent cc3ff5a commit 26dbc64
Show file tree
Hide file tree
Showing 10 changed files with 212 additions and 155 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<br/><br/>

[![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)
Expand Down
90 changes: 55 additions & 35 deletions docs/arguments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -161,24 +161,28 @@ 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
Default: false
```

## 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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -223,17 +227,18 @@ 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
Default: false
```

## 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
Expand All @@ -243,17 +248,18 @@ 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
Default: -
```

## 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
Expand All @@ -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
Expand All @@ -274,7 +280,7 @@ Environment Variable: WATCHTOWER_HTTP_API_METRICS
[Cron expression](https://pkg.go.dev/github.com/robfig/[email protected]?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
Expand All @@ -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
Expand All @@ -295,19 +301,33 @@ 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
Default: 10s
```

## 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
```
24 changes: 17 additions & 7 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
<img alt="Circle CI" src="https://circleci.com/gh/containrrr/watchtower.svg?style=shield" />
</a>
<a href="https://codecov.io/gh/containrrr/watchtower">
<img alt="Codecov" src="https://codecov.io/gh/containrrr/watchtower/branch/master/graph/badge.svg?token=8pxWgB380Y">
<img alt="Codecov" src="https://codecov.io/gh/containrrr/watchtower/branch/main/graph/badge.svg">
</a>
<a href="https://godoc.org/github.com/containrrr/watchtower">
<img alt="GoDoc" src="https://godoc.org/github.com/containrrr/watchtower?status.svg" />
Expand Down Expand Up @@ -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
```
2 changes: 1 addition & 1 deletion docs/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
28 changes: 13 additions & 15 deletions docs/lifecycle-hooks.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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
Expand Down
Loading

0 comments on commit 26dbc64

Please sign in to comment.