Dockcheck

<p align="center"> <img src="extras/dockcheck_colour.png" width="300" title="dockcheck"> </p> <p align="center"> <img src="https://img.shields.io/badge/bash-4.3-green?style=flat-square&logo=gnubash" alt="bash"> <a href="https://www.gnu.org/licenses/gpl-3.0.html"><img src="https://img.shields.io/badge/license-GPLv3-red?style=flat-square" alt="GPLv3"></a> <img src="https://img.shields.io/github/v/tag/mag37/dockcheck?style=flat-square&label=release" alt="release"> <br> <a href="https://ko-fi.com/mag37"><img src="https://img.shields.io/badge/-Ko--fi-grey?style=flat-square&logo=Ko-fi" alt="Buy me a Coffee"></a> <a href="https://liberapay.com/user-bin-rob/donate"><img src="https://img.shields.io/badge/-LiberaPay-grey?style=flat-square&logo=liberapay" alt="LiberaPay"></a> <a href="https://github.com/sponsors/mag37"><img src="https://img.shields.io/badge/-Sponsor-grey?style=flat-square&logo=github" alt="Github Sponsor"></a> <a href="https://www.paypal.com/donate/?business=P2V5MCWRGCNBG&no_recurring=0&currency_code=SEK"><img src="https://img.shields.io/badge/-PayPal-grey?style=flat-square&logo=paypal" alt="PayPal donation"></a> </p> <h2 align="center">CLI tool to automate docker image updates or notifying when updates are available.</h2> <h3 align="center">selective updates, include/exclude containers, image backups, custom labels, notification plugins, prune when done etc.</h3> <h4 align="center">:whale: Docker Hub pull limit :chart_with_downwards_trend: not an issue for checks only for actual pulls - <a href="#whale-docker-hub-pull-limit-chart_with_downwards_trend-not-an-issue-for-checks-but-for-actual-pulls">read more</a></h4> <h5 align="center">For Podman - see the fork <a href="https://github.com/sudo-kraken/podcheck">sudo-kraken/podcheck</a>!</h4>

---

Changelog

• v0.7.7:
  • New:
    • More URLs to urls.list.
    • Allowing ranges to be used when selecting containers to update.
    • Added XMPP notification template.
  • Fixes:
    • Changed "restart-stack" behavior to down+up instead of stop+up.
    • -s option now recreates stopped containers and then stops them again.
• v0.7.6:
  • New:
    • Added Bark notify-template.
  • Fixes:
    • Sanitized message for Matrix notification.
    • Fixed hostname fallback for notifications.
    • Clenaed up README.md some.
    • Sorted and clarified default.config - migrate your settings manually (optional).
• v0.7.5:
  • Added new option BackupForDays; -b N and -B:
    • Backup an image before pulling a new version for easy rollback in case of breakage.
    • Removes backed up images older than N days.
    • List currently backed up images with -B.
  • Fixes:
    • Bugfix for -s Stopped to not recreate stopped containers after update.
• v0.7.4:
  • Added new option -R:
    • Will skip container recreation after pulling images.
    • Allows for more control and possible pipeline integration.
  • Fixes:
    • Bugfix for value too great error due to leading zeroes - solved with base10 conversion.
    • Clean up of some legacy readme sections.

---

dockcheck.sh

$ ./dockcheck.sh -h
Syntax:     dockcheck.sh [OPTION] [comma separated names to include]
Example:    dockcheck.sh -y -x 10 -d 10 -e nextcloud,heimdall

Options:
-a|y   Automatic updates, without interaction.
-b N   Enable image backups and sets number of days to keep from pruning.
-B     List currently backed up images, then exit.
-c D   Exports metrics as prom file for the prometheus node_exporter. Provide the collector textfile directory.
-d N   Only update to new images that are N+ days old. Lists too recent with +prefix and age. 2xSlower.
-e X   Exclude containers, separated by comma.
-f     Force stop+start stack after update. Caution: restarts once for every updated container within stack.
-F     Only compose up the specific container, not the whole compose stack (useful for master-compose structure).
-h     Print this Help.
-i     Inform - send a preconfigured notification.
-I     Prints custom releasenote urls alongside each container with updates in CLI output (requires urls.list).
-l     Only include containers with label set. See readme.
-m     Monochrome mode, no printf colour codes and hides progress bar.
-M     Prints custom releasenote urls as markdown (requires template support).
-n     No updates, only checking availability.
-p     Auto-Prune dangling images after update.
-r     Allow checking/updating images created by `docker run`, containers need to be recreated manually.
-R     Skip container recreation after pulling images.
-s     Include stopped containers, returns to stopped state after recreation.
-t N   Set a timeout (in seconds) per container for registry checkups, 10 is default.
-u     Allow automatic self updates - caution as this will pull new code and autorun it.
-v     Prints current version.
-x N   Set max asynchronous subprocesses, 1 default, 0 to disable, 32+ tested.

Basic example

$ ./dockcheck.sh
[##################################################] 5/5

Containers on latest version:
glances
homer

Containers with updates available:
01) adguardhome
02) syncthing
03) whoogle-search

Choose what containers to update:
Enter number(s) or range(s) separated by comma (e.g. 1-2,4-5,09), [a] for all - [q] to quit: 1-2

Then it proceeds to run pull and up -d on every container with updates.
After the updates are complete, you'll get prompted if you'd like to prune dangling images.

---

Dependencies

• Running docker (duh) and compose, either standalone or plugin. (see Podman fork)
• Bash shell or compatible shell of at least v4.3
  • POSIX xargs, usually default but can be installed with the findutils package - to enable async.
• jq
  • User will be prompted to install with package manager or download static binary.
• regclient/regctl (Licensed under Apache-2.0 License)
  • User will be prompted to download regctl if not in PATH or PWD.
  • regctl requires amd64/arm64 - see workaround if other architecture is used.

Install Instructions

Download the script to a directory in PATH, I'd suggest using ~/.local/bin as that's usually in PATH.
For OSX/macOS preferably use /usr/local/bin.

# basic example with curl:
curl -L https://raw.githubusercontent.com/mag37/dockcheck/main/dockcheck.sh -o ~/.local/bin/dockcheck.sh
chmod +x ~/.local/bin/dockcheck.sh

# or oneliner with wget:
wget -O ~/.local/bin/dockcheck.sh "https://raw.githubusercontent.com/mag37/dockcheck/main/dockcheck.sh" && chmod +x ~/.local/bin/dockcheck.sh

# OSX or macOS version with curl:
 curl -L https://raw.githubusercontent.com/mag37/dockcheck/main/dockcheck.sh -o /usr/local/bin/dockcheck.sh && chmod +x /usr/local/bin/dockcheck.sh

Then call the script anywhere with just dockcheck.sh. Add preferred notify.sh-template to the same directory - this will not be touched by the scripts self-update function.

Configuration

To modify settings and have them persist through updates - copy the default.config to dockcheck.config alongside the script or in ~/.config/.
Alternatively create an alias where specific flags and values are set.
Example alias dc=dockcheck.sh -p -x 10 -t 3.

Notifications

Triggered with the -i flag. Will send a list of containers with updates available and a notification when dockcheck.sh itself has an update. notify_templates/notify_v2.sh is the default notification wrapper, if notify.sh is present and configured, it will override.

Example of a cron scheduled job running non-interactive at 10'oclock excluding 1 container and sending notifications: 0 10 * * * /home/user123/.local/bin/dockcheck.sh -nix 10 -e excluded_container1

Installation and configuration

Set up a directory structure as below. You only need the notify_templates/notify_v2.sh file and any notification templates you wish to enable, but there is no harm in having all of them present.

 .
├── notify_templates/
│   ├── notify_DSM.sh
│   ├── notify_apprise.sh
│   ├── notify_bark.sh
│   ├── notify_discord.sh
│   ├── notify_generic.sh
│   ├── notify_gotify.sh
│   ├── notify_HA.sh
│   ├── notify_matrix.sh
│   ├── notify_ntfy.sh
│   ├── notify_pushbullet.sh
│   ├── notify_pushover.sh
│   ├── notify_slack.sh
│   ├── notify_smtp.sh
│   ├── notify_telegram.sh
│   ├── notify_v2.sh
│   └── notify_xmpp.sh
├── dockcheck.config
├── dockcheck.sh
└── urls.list         # optional

• Uncomment and set the NOTIFY_CHANNELS="" environment variable in dockcheck.config to a space separated string of your desired notification channels to enable.
• Uncomment and set the environment variables related to the enabled notification channels. Eg. GOTIFY_DOMAIN="" + GOTIFY_TOKEN="".

It's recommended to only do configuration with variables within dockcheck.config and not modify notify_templates/notify_X.sh directly. If you wish to customize the notify templates yourself, you may copy them to your project root directory alongside the main dockcheck.sh (where they're also ignored by git).
Customizing notify_v2.sh is handled the same as customizing the templates, but it must be renamed to notify.sh within the dockcheck.sh root directory.

Snooze feature

Configure to receive scheduled notifications only if they're new since the last notification - within a set time frame.

Example: Dockcheck is scheduled to run every hour. You will receive an update notification within an hour of availability.
Snooze enabled: You will not receive a repeated notification about an already notified update within the snooze duration.
Snooze disabled: You will receive additional (possibly repeated) notifications every hour