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](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-type`options.

**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](paypal.me/noccy).