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,
0means up-to-date and
- Pull the updated images with docker-compose, and optionally recreate the containers
- 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.
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
$ composer install $ tools/build.sh
The generated .phar can be found as
To check for updates, pull updated images and recreate any containers defined in the
docker-compose.yml in the current directory:
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
Some of the options can be read from environment variables, for example
--help for supported variables.
- Only checks authenticated registries for new versions. But if you are using this you probably aren't using DockerHub anyway.
- How does Fresh remember the last seen hash? The container hashes are stored
in the same directory as the
docker-compose.ymlfile 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
You can show your appreciation by sending me a donation via Paypal.me: https://paypal.me/noccy.