92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
# 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](https://dev.noccylabs.info/noccy/fresh/releases)
|
|
or [https://files.noccylabs.info/fresh](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](paypal.me/noccy).
|
|
|