From 8ee5575081ecf2c4bc712307b0119d78b088069a Mon Sep 17 00:00:00 2001 From: mag37 Date: Fri, 12 Dec 2025 11:12:57 +0100 Subject: [PATCH] Added option -b to enable image backups pre pull. (#242) * added new variables, options and setup * datecheck function rewrite * moved the cleanup and prune logic to always run. Changed some wording on messages. * added function to print currently backed up images * Patched bugfix to not recreate stopped containers * changed the RepoDigests grab and logic * Moved the backup - cleanup to always trigger if -b option is used. Added -p&-b warning. * version bump and readme fixes --- README.md | 51 +++++++++++++------- default.config | 1 + dockcheck.sh | 128 ++++++++++++++++++++++++++++++++++++++++--------- 3 files changed, 140 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 3b0209e..f811796 100644 --- a/README.md +++ b/README.md @@ -13,15 +13,22 @@

CLI tool to automate docker image updates or notifying when updates are available.

-

selective updates, exclude containers, custom labels, notification plugins, prune when done etc.

+

selective updates, include/exclude containers, image backups, custom labels, notification plugins, prune when done etc.

-

:whale: Docker Hub pull limit :chart_with_downwards_trend: not an issue for checks but for actual pulls - read more

+

:whale: Docker Hub pull limit :chart_with_downwards_trend: not an issue for checks only for actual pulls - read more

For Podman - see the fork sudo-kraken/podcheck!
___ ## Changelog +- **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. @@ -38,16 +45,6 @@ ___ - List reformatting for "available updates" numbering to easier highlight and copy: - Padded with zero, changed `)` to `-`, example: `02 - homer` - Can be selected by writing `2,3,4` or `02,03,04`. -- **v0.7.1**: - - Added support for multiple notifications using the same template - - Added support for notification output format - - Added support for file output - - Added optional configuration variables per channel to (replace `` with any channel name): - - `_TEMPLATE` : Specify a template - - `_SKIPSNOOZE` : Skip snooze - - `_CONTAINERSONLY` : Only notify for docker container related updates - - `_ALLOWEMPTY` : Always send notifications, even when empty - - `_OUTPUT` : Define output format ___ @@ -61,6 +58,8 @@ 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. @@ -86,18 +85,19 @@ Options: ### Basic example: ``` $ ./dockcheck.sh -. . . +[##################################################] 5/5 + Containers on latest version: glances homer Containers with updates available: -1) adguardhome -2) syncthing -3) whoogle-search +01) adguardhome +02) syncthing +03) whoogle-search Choose what containers to update: -Enter number(s) separated by comma, [a] for all - [q] to quit: +Enter number(s) separated by comma, [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. @@ -245,6 +245,23 @@ The `urls.list` file is just an example and I'd gladly see that people contribut Pass `-x N` where N is number of subprocesses allowed, experiment in your environment to find a suitable max! Change the default value by editing the `MaxAsync=N` variable in `dockcheck.sh`. To disable the subprocess function set `MaxAsync=0`. +## Image Backups; `-b N` to backup previous images as custom (retagged) images for easy rollback +When the option `BackupForDays` is set **dockcheck** will store the image being updated as a backup, retagged with a different name and removed due to age configured (*BackupForDays*) in a future run. +Let's say we're updating `b4bz/homer:latest` - then before replacing the current image it will be retagged with the name `dockcheck/homer:2025-10-26_1132_latest` +- `dockcheck` as repo name to not interfere with others. +- `homer` is the image. +- `2025-10-26_1132` is the time when running the script. +- `latest` is the tag of the image. + +Then if an update breaks, you could restore the image by stopping the container, delete the new image, eg. `docker rmi b4bz/homer:latest`, then retag the backup as latest `docker tag dockcheck/homer:_latest b4bz/homer:latest`. +After that, start the container again (now with the backup image active) and it will be updated as usual next time you run dockcheck or other updates. + +The backed up images will be removed if they're older than *BackupForDays* value (passed as `-b N` or set in the `dockcheck.config` with `BackupForDays=N`) and then pruned. +If configured for eg. 7 days, force earlier cleaning by just passing a lower number of days, eg. `-b 2` to clean everything older than 2 days. +Backed up images will not be removed if neither `-b` flag nor `BackupForDays` config variable is set. + +Use the capital option `-B` to list currently backed up images. Or list all images with `docker images`. +To manually remove any backed up images, do `docker rmi dockcheck/homer:2025-10-26_1132_latest`. ## Extra plugins and tools: diff --git a/default.config b/default.config index 2b5f75c..90abfa5 100644 --- a/default.config +++ b/default.config @@ -28,6 +28,7 @@ #CurlRetryCount=3 # Max number of curl retries #CurlConnectTimeout=5 # Time to wait for curl to establish a connection before failing #DisplaySourcedFiles=false # Display what files are being sourced/used +#BackupForDays=7 # Enable backups of images and removes backups older than N days. ### Notify settings ## All commented values are examples only. Modify as needed. diff --git a/dockcheck.sh b/dockcheck.sh index a0150df..906ed0d 100755 --- a/dockcheck.sh +++ b/dockcheck.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -VERSION="v0.7.4" -# ChangeNotes: New option -R to pull without recreation. Fixes: value too great error, legacy cleanups. +VERSION="v0.7.5" +# ChangeNotes: New option -b N to backup image before pulling for easy rollback. Github="https://github.com/mag37/dockcheck" RawUrl="https://raw.githubusercontent.com/mag37/dockcheck/main/dockcheck.sh" @@ -34,6 +34,8 @@ Help() { echo echo "Options:" echo "-a|y Automatic updates, without interaction." + echo "-b N Enable image backups and sets number of days to keep from pruning." + echo "-B List currently backed up images, then exit." echo "-c Exports metrics as prom file for the prometheus node_exporter. Provide the collector textfile directory." echo "-d N Only update to new images that are N+ days old. Lists too recent with +prefix and age. 2xSlower." echo "-e X Exclude containers, separated by comma." @@ -58,6 +60,12 @@ Help() { echo "Project source: $Github" } +# Print current backups function +print_backups() { + printf "\n%b---%b Currently backed up images %b---%b\n\n" "$c_teal" "$c_blue" "$c_teal" "$c_reset" + docker images | sed -ne '/^REPOSITORY/p' -ne '/^dockcheck/p' +} + # Initialise variables Timeout=${Timeout:-10} MaxAsync=${MaxAsync:-1} @@ -77,6 +85,7 @@ Stopped=${Stopped:-""} CollectorTextFileDirectory=${CollectorTextFileDirectory:-} Exclude=${Exclude:-} DaysOld=${DaysOld:-} +BackupForDays=${BackupForDays:-} OnlySpecific=${OnlySpecific:-false} SpecificContainer=${SpecificContainer:-""} SkipRecreate=${SkipRecreate:-false} @@ -97,9 +106,15 @@ c_blue="\033[0;34m" c_teal="\033[0;36m" c_reset="\033[0m" -while getopts "ayfFhiIlmMnprsuvc:e:d:t:x:R" options; do +# Timestamps +RunTimestamp=$(date +'%Y-%m-%d_%H%M') +RunEpoch=$(date +'%s') + +while getopts "ayb:BfFhiIlmMnprsuvc:e:d:t:x:R" options; do case "${options}" in a|y) AutoMode=true ;; + b) BackupForDays="${OPTARG}" ;; + B) print_backups; exit 0 ;; c) CollectorTextFileDirectory="${OPTARG}" ;; d) DaysOld=${OPTARG} ;; e) Exclude=${OPTARG} ;; @@ -156,6 +171,13 @@ if [[ -n "$DaysOld" ]]; then exit 2 fi fi +if [[ -n "$BackupForDays" ]]; then + if ! [[ $BackupForDays =~ ^[0-9]+$ ]]; then + printf "-b argument given (%s) is not a number.\n" "$BackupForDays" + exit 2 + fi + [[ "$AutoPrune" == true ]] && printf "%bWARNING: When -b option is used, -p has no function.%b\n" "$c_yellow" "$c_reset" +fi if [[ -n "$CollectorTextFileDirectory" ]]; then if ! [[ -d $CollectorTextFileDirectory ]]; then printf "The directory (%s) does not exist.\n" "$CollectorTextFileDirectory" @@ -196,11 +218,11 @@ self_update() { printf "\n%s\n" "Pulling the latest version." git pull --force || { printf "%bGit error,%b manually pull/clone.\n" "$c_red" "$c_reset"; return; } printf "\n%s\n" "--- starting over with the updated version ---" - cd - || { printf "%bPath error.%b\n" "$c_red"; return; } + cd - || { printf "%bPath error.%b\n" "$c_red" "$c_reset"; return; } exec "$ScriptPath" "${ScriptArgs[@]}" # run the new script with old arguments exit 0 # exit the old instance else - cd - || { printf "%bPath error.%b\n" "$c_red"; return; } + cd - || { printf "%bPath error.%b\n" "$c_red" "$c_reset"; return; } self_update_curl fi } @@ -209,6 +231,7 @@ choosecontainers() { while [[ -z "${ChoiceClean:-}" ]]; do read -r -p "Enter number(s) separated by comma, [a] for all - [q] to quit: " Choice if [[ "$Choice" =~ [qQnN] ]]; then + [[ -n "${BackupForDays:-}" ]] && remove_backups exit 0 elif [[ "$Choice" =~ [aAyY] ]]; then SelectedUpdates=( "${GotUpdates[@]}" ) @@ -228,16 +251,39 @@ choosecontainers() { } datecheck() { - ImageDate=$("$regbin" -v error image inspect "$RepoUrl" --format='{{.Created}}' | cut -d" " -f1) + ImageDate="$1" + DaysMax="$2" ImageEpoch=$(date -d "$ImageDate" +%s 2>/dev/null) || ImageEpoch=$(date -f "%Y-%m-%d" -j "$ImageDate" +%s) - ImageAge=$(( ( $(date +%s) - ImageEpoch )/86400 )) - if [[ "$ImageAge" -gt "$DaysOld" ]]; then + ImageAge=$(( ( RunEpoch - ImageEpoch )/86400 )) + if [[ "$ImageAge" -gt "$DaysMax" ]]; then return 0 else return 1 fi } +remove_backups() { + IFS=$'\n' + CleanupCount=0 + for backup_img in $(docker images --format "{{.Repository}} {{.Tag}}" | sed -n '/^dockcheck/p'); do + repo_name=${backup_img% *} + backup_tag=${backup_img#* } + backup_date=${backup_tag%%_*} + # UNTAGGING HERE + if datecheck "$backup_date" "$BackupForDays"; then + [[ "$CleanupCount" == 0 ]] && printf "\n%bRemoving backed up images older then %s days.%b\n" "$c_blue" "$BackupForDays" "$c_reset" + docker rmi "${repo_name}:${backup_tag}" && ((CleanupCount+=1)) + fi + done + unset IFS + if [[ "$CleanupCount" == 0 ]]; then + printf "\nNo backup images to remove.\n" + else + [[ "$CleanupCount" -gt 1 ]] && b_phrase="backups" || b_phrase="backup" + printf "\n%b%s%b %s removed.%b\n" "$c_green" "$CleanupCount" "$c_teal" "$b_phrase" "$c_reset" + fi +} + progress_bar() { QueCurrent="$1" QueTotal="$2" @@ -443,7 +489,7 @@ check_image() { if [[ "$LocalHash" == *"$RegHash"* ]]; then printf "%s\n" "NoUpdates $i" else - if [[ -n "${DaysOld:-}" ]] && ! datecheck; then + if [[ -n "${DaysOld:-}" ]] && ! datecheck $("$regbin" -v error image inspect "$RepoUrl" --format='{{.Created}}' | cut -d" " -f1) "$DaysOld" ; then printf "%s\n" "NoUpdates +$i ${ImageAge}d" else printf "%s\n" "GotUpdates $i" @@ -457,7 +503,7 @@ check_image() { # Make required functions and variables available to subprocesses export -f check_image datecheck export Excludes_string="${Excludes[*]:-}" # Can only export scalar variables -export t_out regbin RepoUrl DaysOld DRunUp jqbin OnlyLabel +export t_out regbin RepoUrl DaysOld DRunUp jqbin OnlyLabel RunTimestamp RunEpoch # Check for POSIX xargs with -P option, fallback without async if (echo "test" | xargs -P 2 >/dev/null 2>&1) && [[ "$MaxAsync" != 0 ]]; then @@ -540,11 +586,25 @@ if [[ -n "${GotUpdates:-}" ]]; then for i in "${SelectedUpdates[@]}"; do ((CurrentQue+=1)) printf "\n%bNow updating (%s/%s): %b%s%b\n" "$c_teal" "$CurrentQue" "$NumberofUpdates" "$c_blue" "$i" "$c_reset" - ContLabels=$(docker inspect "$i" --format '{{json .Config.Labels}}') - ContImage=$(docker inspect "$i" --format='{{.Config.Image}}') - ContPath=$($jqbin -r '."com.docker.compose.project.working_dir"' <<< "$ContLabels") + ContConfig=$(docker inspect "$i" --format '{{json .}}') + ContImage=$($jqbin -r '."Config"."Image"' <<< "$ContConfig") + ImageId=$($jqbin -r '."Image"' <<< "$ContConfig") + ContPath=$($jqbin -r '."Config"."Labels"."com.docker.compose.project.working_dir"' <<< "$ContConfig") [[ "$ContPath" == "null" ]] && ContPath="" + # Add new backup tag prior to pulling if option is set + if [[ -n "${BackupForDays:-}" ]]; then + ImageConfig=$(docker image inspect "$ImageId" --format '{{ json . }}') + ContRepoDigests=$($jqbin -r '.RepoDigests[0]' <<< "$ImageConfig") + [[ "$ContRepoDigests" == "null" ]] && ContRepoDigests="" + ContRepo=${ContImage%:*} + ContApp=${ContRepo#*/} + [[ "$ContImage" =~ ":" ]] && ContTag=${ContImage#*:} || ContTag="latest" + BackupName="dockcheck/${ContApp}:${RunTimestamp}_${ContTag}" + docker tag "$ImageId" "$BackupName" + printf "%b%s backed up as %s%b\n" "$c_teal" "$i" "$BackupName" "$c_reset" + fi + # Checking if compose-values are empty - hence started with docker run if [[ -z "$ContPath" ]]; then if [[ "$DRunUp" == true ]]; then @@ -556,7 +616,13 @@ if [[ -n "${GotUpdates:-}" ]]; then continue fi - docker pull "$ContImage" || { printf "\n%bDocker error, exiting!%b\n" "$c_red" "$c_reset" ; exit 1; } + if docker pull "$ContImage"; then + # Removal of the -tag image left behind from backup + if [[ ! -z "${ContRepoDigests:-}" ]] && [[ -n "${BackupForDays:-}" ]]; then docker rmi "$ContRepoDigests"; fi + else + printf "\n%bDocker error, exiting!%b\n" "$c_red" "$c_reset" ; exit 1 + fi + done printf "\n%bDone pulling updates.%b\n" "$c_green" "$c_reset" @@ -569,8 +635,8 @@ if [[ -n "${GotUpdates:-}" ]]; then ((CurrentQue+=1)) unset CompleteConfs # Extract labels and metadata - ContLabels=$(docker inspect "$i" --format '{{json .Config.Labels}}') - ContImage=$(docker inspect "$i" --format='{{.Config.Image}}') + ContConfig=$(docker inspect "$i" --format '{{json .}}') + ContLabels=$($jqbin -r '."Config"."Labels"' <<< "$ContConfig") ContPath=$($jqbin -r '."com.docker.compose.project.working_dir"' <<< "$ContLabels") [[ "$ContPath" == "null" ]] && ContPath="" ContConfigFile=$($jqbin -r '."com.docker.compose.project.config_files"' <<< "$ContLabels") @@ -583,14 +649,22 @@ if [[ -n "${GotUpdates:-}" ]]; then [[ "$ContRestartStack" == "null" ]] && ContRestartStack="" ContOnlySpecific=$($jqbin -r '."mag37.dockcheck.only-specific-container"' <<< "$ContLabels") [[ "$ContOnlySpecific" == "null" ]] && ContRestartStack="" + ContStateRunning=$($jqbin -r '."State"."Running"' <<< "$ContConfig") + [[ "$ContStateRunning" == "null" ]] && ContStateRunning="" + + if [[ "$ContStateRunning" == "true" ]]; then + printf "\n%bNow recreating (%s/%s): %b%s%b\n" "$c_teal" "$CurrentQue" "$NumberofUpdates" "$c_blue" "$i" "$c_reset" + else + printf "\n%bSkipping recreation of %b%s%b as it's not running.%b\n" "$c_yellow" "$c_blue" "$i" "$c_yellow" "$c_reset" + continue + fi - printf "\n%bNow recreating (%s/%s): %b%s%b\n" "$c_teal" "$CurrentQue" "$NumberofUpdates" "$c_blue" "$i" "$c_reset" # Checking if compose-values are empty - hence started with docker run [[ -z "$ContPath" ]] && { echo "Not a compose container, skipping."; continue; } # cd to the compose-file directory to account for people who use relative volumes cd "$ContPath" || { printf "\n%bPath error - skipping%b %s" "$c_red" "$c_reset" "$i"; continue; } - ## Reformatting path + multi compose + # Reformatting path + multi compose if [[ $ContConfigFile == '/'* ]]; then CompleteConfs=$(for conf in ${ContConfigFile//,/ }; do printf -- "-f %s " "$conf"; done) else @@ -610,14 +684,22 @@ if [[ -n "${GotUpdates:-}" ]]; then fi done fi - if [[ "$AutoPrune" == false ]] && [[ "$AutoMode" == false ]]; then printf "\n"; read -rep "Would you like to prune all dangling images? y/[n]: " AutoPrune; fi - if [[ "$AutoPrune" == true ]] || [[ "$AutoPrune" =~ [yY] ]]; then printf "\nAuto pruning.."; docker image prune -f; fi - printf "\n%bAll done!%b\n" "$c_green" "$c_reset" + printf "\n%bAll updates done!%b\n" "$c_green" "$c_reset" + + # Trigger pruning only when backup-function is not used + if [[ -z "${BackupForDays:-}" ]]; then + if [[ "$AutoPrune" == false ]] && [[ "$AutoMode" == false ]]; then printf "\n"; read -rep "Would you like to prune all dangling images? y/[n]: " AutoPrune; fi + if [[ "$AutoPrune" == true ]] || [[ "$AutoPrune" =~ [yY] ]]; then printf "\nAuto pruning.."; docker image prune -f; fi + fi + else - printf "\nNo updates installed, exiting.\n" + printf "\nNo updates installed.\n" fi else - printf "\nNo updates available, exiting.\n" + printf "\nNo updates available.\n" fi +# Clean up old backup image tags if -b is used +[[ -n "${BackupForDays:-}" ]] && remove_backups + exit 0