fresh/README.md

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.

Building

Build using NoccyLabs Pharlite, included in the tools directory. Don't forget to run composer to install dependencies first.

$ composer install
$ tools/pharlite

Installing

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.

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

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

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.

Changes

0.1.1

• Moved the logic from the entrypoint script to its own class.
• Added locking (though fresh.lock lockfile) to prevent multiple instances.
• Added --after hook to invoke script after update.
• Disabled automatic flushing of the state to disk; --check will no longer update the state file, but --pull and default update will.

0.1.2

• Fixed a bug in lockfile class preventing release of stale lockfile.
• The --image option finally works.
• Added a --write-state/-w option to write updated hashes to the state file.
• Implemented --config and --config-typeoptions.

0.1.3

• Added a --before script hook, to complement the --after hook.
• Hooks now invoked both before and after deploy.

Thank you?

You can show your appreciation for the time and sweat you have saved through Paypal.me: https://paypal.me/noccy.