janjk/docker-container-updater repository overview

⁠Docker Container Updater

For all the lazier and automation-loving nerds, constantly updating Docker containers can be a tedious chore. Enter the Docker Container Updater to save the day. It handles updates without relying on the "latest" tag or sticking to the current image tag, which might cause you to miss important updates. Instead, it plays by your rules!

🌱 This project is currently in its early stages, and any feedback on potential issues would be greatly appreciated.

⁠Features

• 🔄 Automated Container Updates: Effortlessly update all your Docker containers on your host under your own conditions.
• 🧠 Smart Update Detection: This tool creates a regex filter based on the currently used image tag and scans Docker Hub for any available updates. It automatically analyzes the version numbers specified in the image tags and identifies major, minor, patch, and build updates. It also handles simple digest updates automatically.
• ⚙️ Customizable and Conditional Update Rules: Define highly precise update rules for each individual container.
• 🔁 Standard Update Sequence: Updates follow the standard sequence: first digest, build, patch, minor, and then major updates. No updates are skipped.
• 🛠️ Backup and Rollback: Backups of your containers are created before updates. If an update fails, the change is rolled back and the old container is restarted.
• 📧 Notifications: Stay informed with detailed email and telegram reports
• 📜 Pre- and Post-Scripts Integration: Integrate your own pre- and post-scripts to perform actions such as backing up configuration files or databases before any update and making adjustments to the container configuration after any update.

⁠Getting Started

⁠Using Docker CLI

⁠Example Command

Use the following command to run Docker Container Updater with basic configuration and test mode explicitly enabled:

docker run  -d \
            --name=Docker-Container-Updater \
            --hostname=Docker-Container-Updater \
            --restart=always \
            --privileged \
            --tty \
            --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
            --mount type=bind,source=/etc/localtime,target=/etc/localtime,readonly \
            --env DCU_TEST_MODE=true \
            --env DCU_CRONTAB_EXECUTION_EXPRESSION='30 2 * * *' \
            janjk/docker-container-updater:latest

⁠Data Persistence

To ensure data persistence, you should configure the following mounts:

--mount type=bind,source=<YOUR_LOCAL_PRE_SCRIPTS_PATH>,target=/usr/local/etc/container_update/pre-scripts \
--mount type=bind,source=<YOUR_LOCAL_POST_SCRIPTS_PATH>,target=/usr/local/etc/container_update/post-scripts \
--mount type=bind,source=<YOUR_LOCAL_LOGS_PATH>,target=/var/log \

⁠Run Your First Test

After successfully starting Docker Container Updater, a cron job inside the container will automatically manage the update mechanism for your Docker containers based on the cron expression defined in DCU_CRONTAB_EXECUTION_EXPRESSION.

To manually execute the update process, run:

docker exec -it Docker-Container-Updater dcu --run

If you have already disabled test mode in your configuration, you can enforce using test mode for this one time execution by running the following command (>= v2024.06.07-1):

docker exec -it Docker-Container-Updater dcu --dry-run

⁠Configuration

You can fully configure Docker Container Updater by setting environment variables in your docker run command.

⁠Configure Notifications

⁠E-Mail Notifications

⁠General Information

In order to receive E-Mail notifications you need to have a Mail Transfer Agent (MTA) (e.g., Postfix) installed, configured and reachable in your network, to which the Docker container can relay its emails. The IP address or the hostname of your MTA needs be specified in the environment variable DCU_MAIL_RELAYHOST when running the container.

⁠Docker CLI

--env DCU_REPORT_REAL_HOSTNAME="$(hostname)" \
--env DCU_REPORT_REAL_IP="$(hostname -I | awk '{print $1}')" \
--env DCU_REPORT_REAL_DOCKER_VERSION="$(docker --version | awk '{print $3}' | tr -d ',')" \
--env DCU_MAIL_NOTIFICATIONS_ENABLED=true \
--env DCU_MAIL_FROM='<[email protected]>' \
--env DCU_MAIL_RECIPIENTS='<[email protected]>' \
--env DCU_MAIL_SUBJECT="🐳 Docker Container Update Report from $(hostname)" \
--env DCU_MAIL_RELAYHOST='[<IP address or hostname>]:<Port>' \

⁠Telegram Notificationss

⁠General Information

To receive Telegram notifications, you first need to obtain a Chat ID and a Bot Token.

⁠Docker CLI

--env DCU_REPORT_REAL_HOSTNAME="$(hostname)" \
--env DCU_REPORT_REAL_IP="$(hostname -I | awk '{print $1}')" \
--env DCU_REPORT_REAL_DOCKER_VERSION="$(docker --version | awk '{print $3}' | tr -d ',')" \
--env DCU_TELEGRAM_NOTIFICATIONS_ENABLED=true \
--env DCU_TELEGRAM_BOT_TOKEN='<your_bot_token>' \
--env DCU_TELEGRAM_CHAT_ID='<your_chat_id' \

⁠Configure Update Rules

The DCU_UPDATE_RULES environment variable allows you to define the update behavior for your containers. The default rule is *[0.1.1-1,true], which means:

• *: Applies to all containers.
• 0.1.1-1: Specifies the update policy, where each number represents:
  • 0: Major updates (0 means no major updates, 1 means allow major updates to the next available, 2 means always stay one version behind the latest major release, and so on)
  • 1: Minor updates (0 means no minor updates, 1 means allow minor updates to the next available, 2 means always stay one version behind the latest minor release, and so on)
  • 1: Patch updates (0 means no patch updates, 1 means allow patch updates to the next available, 2 means always stay one version behind the latest patch release, and so on)
  • 1: Build updates (0 means no build updates, 1 means allow build updates to the next available, 2 means always stay one version behind the latest build release, and so on)
• true: Indicates that digest updates are allowed.

You can customize these rules for each container by specifying different patterns and update policies separated by spaces.

⁠Basic Rule Example

*[0.1.1-1,true] mycontainer[1.0.0-1,true] another[0.0.1-1,false] further[2.1.1-1,true]

⁠Precise Rule Examples

You can also create more specific rule sets that allow, for example, major updates for a container if at least one patch has been released for that major version. In the rules, 'M' stands for Major, 'm' for Minor, 'p' for Patch, and 'b' for Build.

mycontainer[1&(p>1).1.1-1,true]

mycontainer[0.1&(b>2).1-1,true]

These precise rules provide granular control over the update behavior of specific containers based on various conditions such as patch versions, build versions, and more.

⁠Pre- and Post-Scripts

To give you more control, you can integrate your own pre- and post-scripts. These are created by default in the directories /usr/local/etc/container_update/pre-scripts and /usr/local/etc/container_update/post-scripts within the container, and they must be named after the relevant container. These are standard bash scripts that you can create and customize as needed. For example, you can create backups of databases, configuration files, etc., before updating a container, and make adjustments such as customized branding or changes to file permissions after any update. Essentially, you can tailor these scripts to your specific needs. The output of these scripts is redirected to the log of Docker Container Updater, so you have all logs in one place.

⁠When are the Pre- and Post-Scripts executed?

⁠Description of the Update Process

1. A pre-script is executed as soon as all conditions for an update are met:

   • The effective rule for the respective container allows an update

   • The age of the image on Docker Hub meets the configured minimum age in DCU_DOCKER_HUB_IMAGE_MINIMUM_AGE

   • The new image has been successfully downloaded

   Only at this point is the pre-script executed. Once the pre-script has been processed, the procedure continues as follows...

2. The original container is renamed (to allow for a backup of the container)

3. The startup policy of the original container is overwritten (to prevent simultaneous startups)

4. The original container is stopped

5. The new container with the new image is started

6. If the new container was successfully started, the post-script is now executed.

⁠Command Line Parameters

Usage: dcu [ [--dry-run|--run] [--filter name|id=VALUE] [--force] ] [--help] [--version]
Options:
  --dry-run    -dr        Run DCU in dry-run mode (this temporarily enforces test mode to be enabled)
  --force      -f         Force lock acquisition
  --help       -?         Display this help
  --run        -r         Run DCU (considering the current configuration for test mode)
  --version    -v         Display the current version
  --debug                 Set log level to debug mode

Usage: dcu [--dry-run|--run] [ --filter [options|--help] ]
Options:
  --filter                Filter processed containers by the following conditions:
                            name=My_Container_Name
                            id=My_Container_ID

You can get more information about this project on GitHub⁠