# 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).