# mag37/dockcheck architecture

> Architecture diagram of the GitHub repository mag37/dockcheck, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mag37/dockcheck
- Repository: https://github.com/mag37/dockcheck

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Components"
        CLI["CLI Interface (dockcheck.sh)"]:::core
        CONFIG["Configuration Module (default.config)"]:::core
        UPDATE["Update Checker/Executor (dockcheck.sh)"]:::core
    end

    subgraph "Notification Subsystem"
        NOTIFY["Notification Subsystem (notify_templates)"]:::noti
        NURL["Notification URL Lookup (notify_templates/urls.list)"]:::noti
    end

    subgraph "Monitoring & Metrics"
        METRICS["Metrics Integration (addons/prometheus)"]:::monitoring
        PROM_COLLECTOR["Prometheus Collector (prometheus_collector.sh)"]:::monitoring
        GRAFANA["Grafana Dashboard (grafana_dashboard.json)"]:::monitoring
    end

    subgraph "External Dependencies"
        DOCKER["Docker Daemon/API"]:::external
        COMPOSE["Docker-Compose"]:::external
        BASH["Bash Shell (v4.3+)"]:::external
        TOOLS["External Tools (jq,regctl,xargs)"]:::external
    end

    CLI -->|"UserInput"| UPDATE
    CONFIG -->|"Configures"| UPDATE
    UPDATE -->|"Interacts"| DOCKER
    UPDATE -->|"Manages"| COMPOSE
    UPDATE -->|"ChecksRegistry"| TOOLS
    UPDATE -->|"TriggersNotification"| NOTIFY
    NOTIFY -->|"UsesLookup"| NURL
    CLI -->|"RunsIn"| BASH
    UPDATE -->|"ParallelCheck"| TOOLS
    METRICS -->|"ExportsMetrics"| DOCKER
    METRICS -->|"UsesCollector"| PROM_COLLECTOR
    METRICS -->|"VisualizesVia"| GRAFANA

    click CLI "https://github.com/mag37/dockcheck/blob/main/dockcheck.sh"
    click CONFIG "https://github.com/mag37/dockcheck/blob/main/default.config"
    click NOTIFY "https://github.com/mag37/dockcheck/tree/main/notify_templates"
    click NURL "https://github.com/mag37/dockcheck/blob/main/notify_templates/urls.list"
    click METRICS "https://github.com/mag37/dockcheck/tree/main/addons/prometheus"
    click PROM_COLLECTOR "https://github.com/mag37/dockcheck/blob/main/addons/prometheus/prometheus_collector.sh"
    click GRAFANA "https://github.com/mag37/dockcheck/blob/main/addons/prometheus/grafana/grafana_dashboard.json"

    classDef core fill:#FAD7A0,stroke:#C0392B,stroke-width:2px;
    classDef noti fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef monitoring fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
```
