dockmate 0.1.14
Monitors a list of specified Docker containers and automatically upgrades them when new images are released.
License: MIT
Requires Python: >=3.13

# dockmate

<p align="center">
  <img src="https://raw.githubusercontent.com/antrax2024/dockmate/refs/heads/main/src/dockmate/assets/banner-logo.jpg" alt="DockMate Logo">
</p>

<div align="center">
  <span>
    <img alt="PyPI - Version" src="https://img.shields.io/pypi/v/dockmate">
    <img alt="AUR Version" src="https://img.shields.io/aur/version/dockmate">
    <img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fantrax2024%2Fdockmate%2Frefs%2Fheads%2Fmain%2Fpyproject.toml" alt="Python Version" />
    <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/antrax2024/dockmate">
    <img alt="PyPI - License" src="https://img.shields.io/pypi/l/dockmate">
  </span>
</div>

**dockmate** is a Python application that monitors a list of specified Docker containers and automatically upgrades them when new images are released.

This application runs continuously and, as soon as it detects a new remote **image:tag** version, automatically updates the container to the latest version seamlessly.

## Features

- Monitors specified Docker containers for available image updates.
- Automatically pulls the latest image and restarts the container with the new image.
- Configurable monitoring interval.
- Supports connection to local or remote Docker daemons.
- Send [Pushover](https://pushover.net/) Notifications if container updated.

## Installation

You can install **dockmate** using several methods:

### PyPI

Install the latest stable version from [PyPI](https://pypi.org/https:/):

```bash
pip install dockmate
```

or using uv:

```bash
uv pip install dockmate
```

### Docker Container (Recomended)

You can run **dockmate** as a docker container, which is the official and recommended way.

1. Clone the git repository:

```bash
git clone https://github.com/antrax2024/dockmate.git
```

2. Edit the **config/config.yaml** file with the necessary parameters for your case.

```bash
nvim ./config/config.yaml
```

3. Start the container:

```bash
docker compose up -d --build
```

4. To view logs, run the following command:

```bash
docker logs -f dockmate
```

### Arch User Repository (AUR)

If you are using an Arch-based Linux distribution, you can install dockmate from the AUR using an AUR helper like `yay` or `paru`:

```bash
yay -S dockmate
```

or

```bash
paru -S dockmate
```

## Command-Line Interface

The application uses `click` for its command-line interface.

```bash
dockmate [OPTIONS]
```

### Options

- `-h`, `--help`: Show the help message and exit.
- `-c`, `--config FILE`: Specifies the path to the `config.yaml` file.
  - Default: `~/.config/dockmate/config.yaml`
  - If the specified file does not exist, dockmate will create a default configuration file at that location.

## Configuration

dockmate uses a YAML file (`config.yaml`) for configuration.

### Default Location

By default, dockmate looks for the configuration file at: `~/.config/dockmate/config.yaml`

You can specify a different location using the `-c` or `--config` command-line option.

### Configuration Parameters

The `config.yaml` file contains the following parameters:

- `docker_host`: (String) The URL of the Docker daemon API endpoint.

  - Use `"unix:///var/run/docker.sock"` for the local Docker daemon via Unix socket.
  - Use `"tcp://hostname:port"` (e.g., `"tcp://192.168.1.100:2375"`) to connect to a remote Docker daemon.
  - _Example:_ `docker_host: "tcp://192.168.1.16:2375"`

- `containers`: (List of Strings) A list of Docker container names that dockmate should monitor and update.

  - These names must match the actual names of your running containers.
  - _Example:_ `containers: ["adguardhome", "homepage", "portainer"]`

- `pushover`: (Boolean) Enable or disable Pushover notifications

  - Controls whether Pushover notifications are enabled.
  - When set to true, the application will send notifications through the Pushover service.
  - When set to false, Pushover notifications will be disabled.

Nota Importante:

You need to be registered on the [Pushover](https://pushover.net/login) service, create an API key and a User key. Once done, create the following environment variables:

```ini
PUSHOVER_USER_KEY = your_pushover_user_key
PUSHOVER_API_TOKEN = your_app_pushover_api_token
```

If you don't register the environment variables, or don't even register for the service, it obviously won't work because there's no magic.

- `time_main_loop`: (Integer) The interval in seconds between checks for container image updates.

  - The application will pause for this duration after completing a check cycle.
  - _Example:_ `time_main_loop: 7200` (Check every 2 hours)

### Example `config.yaml`

```yaml
# dockmate configuration file

# docker_host represents the Docker host URL used for communication with the Docker daemon.
# This allows the Docker client to connect to the Docker Engine, which could be local or remote.
# Example values include: "unix:///var/run/docker.sock" for local Unix socket connection
# or "tcp://hostname:port" for a remote Docker host.
docker_host: "unix:///var/run/docker.sock" # Docker host URL

# containers: Docker containers that will be monitored by the application.
# This configuration defines the list of Docker containers that the application
# will track and monitor for status, resource usage, and other metrics.
# Example container configuration
# containers: ["mariadb", "nginx", "redis", "postgres" ]
containers: []

# Controls whether Pushover notifications are enabled.
# When set to true, the application will send notifications through the Pushover service.
# When set to false, Pushover notifications will be disabled.
# @type: boolean
# @default: true
# Remember, you need the follow environment variables set:
# PUSHOVER_USER_KEY
# PUSHOVER_API_TOKEN
pushover: false # Enable or disable Pushover notifications. Default is false.

# time_main_loop: This parameter specifies the interval between each main loop iteration.
time_main_loop: 7200
```

## Usage

Once installed and configured, simply run the command:

```bash
dockmate
```

Or, if you need to specify a custom configuration file path:

```bash
dockmate --config /path/to/your/custom_config.yaml
```

dockmate will then start monitoring the specified containers according to the configuration.

## License

dockmate is released under the MIT License. See the [LICENSE](LICENSE) file for details.

Copyright (c) 2020 Paul O'Leary McCann