Skip to content

# Lifecycle hooks

## Executing commands before and after updating

Note

These are shell commands executed with `sh`, and therefore require the container to provide the `sh` executable.

> DO NOTE: If the container is not running then lifecycle hooks can not run and therefore the update is executed without running any lifecycle hooks.

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

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) or be specified as part of the `docker run` command line:

Dockerfile docker run

    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"

    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

The timeout for all lifecycle commands is 60 seconds. After that, a timeout will occur, forcing Watchtower to continue the update loop.

#### Pre- or Post-update timeouts

For the `pre-update` or `post-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` or post-update-timeout respectively followed by the timeout expressed in minutes.

If the label value is explicitly set to `0`, the timeout will be disabled.

### Execution failure

The failure of a command to execute, identified by an exit code different than 0 or 75 (EX_TEMPFAIL), will not prevent watchtower from updating the container. Only an error log statement containing the exit code will be reported.