Fresh: Keeping your docker stacks up to date

Fresh was written to scratch an itch. It works by querying the respective repositories for the various manifests in order to determine if the images have been changed. If so it can do a combination of things:

• Set the exitcode to indicate the freshness, 0 means up-to-date and 1 outdated.
• Pull the updated images with docker-compose, and optionally recreate the containers with docker-compose up.
• Run a script before and after updating, f.ex. to enable maintenance mode or update permission on volumes.
• Notify webhooks when updating. Currently only Slack and Mattermost are supported.

Fresh is designed to be invoked using cron or systemd timers, and as such provides a light-weight easy-to-use alternative to more complex toolkits.

How to install

Fresh requires PHP 8.0 or later.

Download the latest version (or build it yourself) and move it into /usr/bin. You can grab it at https://dev.noccylabs.info/noccy/fresh/releases or https://files.noccylabs.info/fresh

Building

Build using NoccyLabs Pharlite, included in the tools directory. Don't forget to run composer to install dependencies first. In order to properly generate or update the version file, use the build.sh script:

$ composer install
$ tools/build.sh

The generated .phar can be found as fresh.phar and dist/fresh-VERSION.phar.

Usage

To check for updates, pull updated images and recreate any containers defined in the docker-compose.yml in the current directory:

$ fresh.phar 

Specify a directory to chdir into; very useful with cron:

$ fresh.phar --dir /srv/docker/mystack

To invoke scripts or webhooks:

$ fresh.phar --before scripts/sitedown.sh --after scripts/siteup.sh \
    --slack https://my.slack.or/mattermost/webhook

Check a specific image:

$ fresh.phar --image my.private.repo/name/package:latest --check -w
$ echo $?  # if 1, a newer version is available

Check images defined in a custom configuration file:

$ cat freshdocker.conf
check:
- my.docker.repo/vendor/image:latest
$ bin/freshdocker -C fresh --check -v
# ..or..
$ bin/freshdocker -c freshdocker.conf --check -v

For all available options, use the --help flag.

Some of the options can be read from environment variables, for example FRESH_AFER or FRESH_SLACK. See --help for supported variables.

Known Issues

• Only checks authenticated registries for new versions. But if you are using this you probably aren't using DockerHub anyway.

FAQ

• How does Fresh remember the last seen hash? The container hashes are stored in the same directory as the docker-compose.yml file in a file named fresh.yml. Remove this file to force trigger an update.
• What are these hashes? Fresh grabs the manifest for the image from the registry and proceeds to hash a concatenation of all the various build layer hashes. This should mean if the image is new but the layers are the same nothing will be updated.
• How do I notify a Mattermost webhook? Mattermost webhooks are compatible with Slack webhooks, so simply use the --slack flag.

Thank you?

You can show your appreciation by sending me a donation via Paypal.me: https://paypal.me/noccy.