How mag37/dockcheck works
Project Type and Purpose
• This is a CLI tool (written in Bash) designed to automate Docker image updates. It checks for available updates, pulls newer images, and restarts containers (or compose stacks) accordingly. It also supports selectively updating containers, excluding certain ones, and integrates with various notification systems to alert users about available updates.
• In addition, there’s an addons section (e.g., for Prometheus and Grafana) that adds metrics collection and monitoring capabilities.
Analyzing the File Structure
• At the top level, you have:
• The main script (“dockcheck.sh”) which serves as the entry point.
• A configuration file (“default.config”), which can be copied as “dockcheck.config” for persistent settings.
• A “notify_templates” directory housing various notification script templates (for DSM, Apprise, Slack, Telegram, etc.).
• An “addons” directory containing an integration module for Prometheus (and a Grafana dashboard JSON), signifying the project’s extensibility.
• An “extras” folder with supplementary scripts (like errorCheck.sh), documentation (Apprise quickstart), and assets (logo and example GIF).
• The structure indicates modular components:
• Core update logic (the “dockcheck.sh” script)
• Configuration management (via config files)
• Notification subsystem (with multiple scripts under notify_templates)
• Additional integrations (Prometheus metrics export and Grafana dashboards in the addons folder)
Main Components
• CLI Interface & Input Parsing:
• The “dockcheck.sh” entrypoint that handles command-line options (automatic updates, exclusion lists, timeout settings, asynchronous options, etc.)
• Input flags and user interaction (help display, interactive prompts for updating containers)
• Update Checker/Executor:
• Core logic that identifies outdated Docker images by interacting with the Docker daemon.
• Uses external tools like “jq” for JSON parsing and “regctl” for registry checks.
• Implements asynchronous update checks via xargs (with configurable max subprocesses).
• Configuration Module:
• Reads settings from “default.config” (or user’s copied “dockcheck.config”) to drive persistent behavior.
• Notification Subsystem:
• A set of plug-in templates (each a separate script such as notify_slack.sh, notify_telegram.sh, etc.) that trigger notifications either pre- or post-update.
• The integration of a “notify.sh” copy (user-modified version) that is not overwritten by updates.
• Metrics and Monitoring Integration:
• The Prometheus addon (in addons/prometheus) including utilities to export metrics files for node_exporter.
• A Grafana dashboard JSON template, showing how the project supports visual monitoring.
• External Dependencies:
• Docker (and docker-compose) for container manipulation.
• Bash (minimum version 4.3) providing shell features.
• Tools like “jq” and “regctl” that are core to the registry check and async processing.
• Notification URL lookup file:
• The “notify_templates/urls.list” that maps container names to release note URLs for enhanced notification content.
Relationships & Interactions Between Components
• The CLI Interface accepts user-specified flags that configure the behavior of the Update Checker.
• The Update Checker interacts with the Docker daemon, using Docker CLI commands to inspect, pull, and restart containers.
• As part of the update process, it checks image registry information (using “regctl”) and parses response data via “jq.”
• Once updates are determined or executed, the Notification Subsystem is invoked. The scripts in the “notify_templates” directory are used to send alerts based on the user’s chosen method.
• Optionally, if the “-c” option is used, the system exports metrics to a specified directory for consumption by Prometheus/node_exporter.
• Configuration and user settings (persisted in the config file) control flow behaviors (asynchronous settings, how to handle containers, etc.)
Architectural Patterns and Design Principles
• Modularity: The project explicitly separates core logic (main update script) from optional integrations (such as notifications and Prometheus).
• Extensibility: The use of templates in the notify_templates directory allows for easy extension of notification methods without altering the core logic.
• Asynchronous Processing: Leveraging tools like xargs to enable parallel registry checks.
• Separation of Concerns: By splitting configuration, notifications, and update checking into distinct areas, changes in one part (e.g., adding a new notification method) don’t require core logic modifications.
• External Integration: Clear interfaces to Docker, external registries, and monitoring systems.