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