<!--  --> <center><img alt="image" src="https://github.com/user-attachments/assets/cb264d67-7d72-4527-9a27-4599a6f9d1c2"></center> <br>

MqDockerUp

MqDockerUp is a tool that allows you to monitor and update your docker containers using MQTT and homeassistant. It can publish information about your containers, such as name, status, image, ports, etc., to an MQTT broker, and create or update corresponding entities in homeassistant. You can also send commands to start, stop, pause, unpause, restart, or remove your containers via MQTT or homeassistant. It even creates update entities in Homeassistant to make it easy to update your running containers. MqDockerUp is easy to set up and configure, and supports multiple platforms and architectures. With MqDockerUp, you can have a unified and convenient way to manage your docker containers from anywhere.

How it works

MqDockerUp uses various Docker Registry APIs (DockerHub/GHCR/LSCR) to get information about containers and images. It then makes a request to the Docker Hub API to get information about the latest image tags. If there is a new version, it will publish the change to a specified MQTT broker.

How to use

Standalone application

1. Clone the repository and install dependencies withnpm install.
2. Change theconfig.yaml file with your desired configuration.
3. Run the project withnpm run start.

Docker

• Docker run
• Docker Compose/Docker-compose

Notable Path/Binds/Volumes

• Path required to access the docker API: /var/run/docker.sock:/var/run/docker.sock
• Path required to store the data (database.db): your/path/data:/app/data/
• Path required if you want to use yaml config: your/path/config.yaml:/app/config.yaml

Configuration

The configuration file config.yaml (\app\config.yaml in docker the container) contains the following sections:

Main Configuration

The main configuration is specified in the main section of config.yaml:

| Name | Environmental Variable | Type | Default | Description | | -----------------------: | :---------------------------: | :------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | containerCheckInterval | MAIN_CONTAINERCHECKINTERVAL | string | "5m" | The interval at which container are checked and published/republished to the MQTT broker, must be in the format[number][unit], where [number] is a positive integer and [unit]. | | containerCheckOnChanges | MAIN_CONTAINERCHECKONCHANGES | boolean | true | Trigger a container check when Docker emits container lifecycle events (create, start, stop, destroy, etc.). Set to false to only use the interval check. Recommended for environments with many containers to reduce MQTT message traffic. | | updateCheckInterval | MAIN_UPDATECHECKINTERVAL | string | "" | The interval at which updates are checked and published/republished to the MQTT broker, must be in the format[number][unit], where [number] is a positive integer and [unit] <br> (same of containerCheckInterval if ""). | | prefix | MAIN_PREFIX | string | "" | Parameter specifies a prefix to add to the MQTT topic when publishing updates. Enabling you to have multiple instances of MqDockerUp publishing to the same MQTT broker without conflicts. |

[!WARNING] If you upgrade from version 1.14.0 (or lower), some name are changed:

• main.interval/MAIN_INTERVAL is now main.containerCheckInterval/MAIN_CONTAINERCHECKINTERVAL.
• main.imageUpdateInterval/MAIN_IMAGEUPDATEINTERVAL is now main.updateCheckInterval/MAIN_UPDATECHECKINTERVAL.

<a name="Unit"></a>[Unit]

| Unit | s | m | h | d | w | | ----------: | :-----: | :-----: | :---: | :--: | :---: | | Meaning | Seconds | Minutes | Hours | Days | Weeks |

MQTT Configuration

The MQTT configuration is specified in the mqtt section of config.yaml:

| Name | Environmental Variable | Type | Default | Description | | ----------------: | :--------------------: | :-------: | :---------------------: | :------------------------------------------------------------------------------------------------------ | | connectionUri | MQTT_CONNECTIONURI | string | mqtt://127.0.0.1:1883 | The URL of the MQTT broker to connect to. | | topic | MQTT_TOPIC | string | mqdockerup | The MQTT topic to publish updates to. | | discoveryPrefix | MQTT_DISCOVERYPREFIX | string | homeassistant | The Prefix chosen in HA as discovery prefix (change only if you changed it in HA) | | suggestedArea | MQTT_SUGGESTEDAREA | string | Docker | The Home Assistant suggested area to assign to created devices. | | clientId | MQTT_CLIENTID | string | mqdockerup | The MQTT client ID to use when connecting to the broker. | | username | MQTT_USERNAME | string | ha | The username to use when connecting to the MQTT broker. | | password | MQTT_PASSWORD | string | "" | The password to use when connecting to the MQTT broker. | | haLegacy | MQTT_HALEGACY | boolean | false | The way MqDockerUp creates the update entity, false for HA 2024.11+ and true for previous versions. | | connectTimeout | MQTT_CONNECTTIMEOUT | int | 60 | The maximum time, in seconds, to wait for a successful connection to the MQTT broker. | | protocolVersion | MQTT_PROTOCOLVERSION | int | 5 | The MQTT protocol version to use when connecting to the broker. | | maxReconnectDelay | MQTT_MAXRECONNECTDELAY | int | 300 | The maximum time, in seconds, between reconnection attempts when disconnected from the MQTT broker. |

Access Tokens Configuration

The access tokens configuration is specified in the accessTokens section of config.yaml:

| Name | Environmental Variable | Type | Default | Description | | ----------: | :----------------------: | :------: | :-----: | :----------------------------------------------------------------------------------------------------- | | dockerhub | ACCESSTOKENS_DOCKERHUB | string | "" | The Dockerhub token, used to avoid the limitations of the DockerHub API ‼️Still Work In Progress. | | github | ACCESSTOKENS_GITHUB | string | "" | The Github token, used to manage images on GitHub (ghcr.io) ⚠️Needed for this type of images. |

[!NOTE] To setup GitHub access token:

Setup a Fine-grained personal access token with the following permissions:

• Repository Access -> All repositories
• Repository Permissions (Read-Only):
  • Commit Statuses
  • Contents
  • Merge queues
  • Metadata
  • Pull requests

Ignore Configuration

The ignore configuration is specified in the ignore section of config.yaml:

| Name | Environmental Variable | Type | Default | Description | | -----------: | :-------------------: | :------: | :-----: | :------------------------------------------------------------------------------------------------------------------ | | containers | IGNORE_CONTAINERS | string | "" | A comma separated list of container to be ignored in the check, or * to ignore all containers . | | updates | IGNORE_UPDATES | string | "" | A comma separated list of container which updates should be ignored in the check, or * to ignore all containers . |

Logs Configuration

The ignore configuration is specified in the logs section of config.yaml:

| Name | Environmental Variable | Type | Default | Description | | ------: | :-------------------: | :------: | :------: | :-------------------------------------------------------------------------------------------------------------- | | level | LOGS_LEVEL | string | "info" | Choose the maximum level of logs to show, i