gameplayer8/compose-updater repository overview

⁠Compose Updater

A solution for watching your Docker® containers running via Docker Compose for image updates and automatically restarting the compositions whenever an image is refreshed.

⁠Overview

Compose Updater is an application which continuously monitors your running docker containers. When an image is updated, the updated version gets pulled (or built via --pull) from the registry and the docker compose composition gets restarted (via down and up -d).

Compose Updater is useful for your when you're using image tags which are updated regularly (such as image:latest or a specific major version like image:v3).

Currently, Compose Updater doesn't help you when your're using image tags that won't change (such as an unchangable SemVer, i.e. image:1.2.3). It won't update your Docker Compose files to use newer image tags.

⁠Usage

⁠1. Prepare your services

You'll need to add two labels to the services you want to watch:

services:
  web:
    image: nginx:alpine
    labels:
      - "docker-compose-watcher.watch=1"
      - "docker-compose-watcher.dir=/home/docker/dir"

docker-compose-watcher.watch=1 exposes the service to Compose Updater.

docker-compose-watcher.dir specifies the path to the directory where this docker-compose.yml lives. If the file is not named docker-compose.yml, you can instead use the label docker-compose-watcher.file to specify the correct path and file name. This is necessary because it's not possible to find the docker-compose.yml from a running container.

⁠2. Run Compose Updater

Run Docker Compose Watcher using compose:

services:
  watcher:
    image: gameplayer8/compose-updater
    restart: always
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "/home/docker:/home/docker:ro"
    environment:
      INTERVAL: 60

It's important to mount /var/run/docker.sock and the directory your compose files reside in (/home/docker in the example above).

If the registry you're pulling from require authentification, you could mount ~/.docker/config.json from the host inside the watcher service. Assuming your host user is called ubuntu, adding this line to the volumes declaration of the watcher service should work :

volumes:
  # Mount repository configuration (including http(s) settings and credentials) from the host to the container (assuming the host user is called ubuntu)
  - "/home/ubuntu/.docker/config.json:/root/.docker/config.json:ro"

Note: You'll only need one Compose Updater instance for all your compose services (not one per docker-compose.yml).

⁠Settings

Configure Compose Updater via environment variables (recommended) or command line arguments:

⁠Connecting an MQTT Broker

You can connect Compose Updater to an MQTT Broker (such as Eclispe Mosquitto or HiveMQ). This way, the actions of each run (i.e. image pulls, composition restarts) are published to an MQTT topic. You can use these informations to send push notifications using a solution like mqttwarn⁠ or Home Assistant⁠.

To connect to an MQTT broker, specify the required connection parameters in the settings (see above).

Compose Updater published the following topics:

⁠Push notification example

The following Home Assistant⁠ configuration sends a message via Telegram whenever a Docker composition has been restarted after updating at least one image:

automation:
  - alias: "Docker Compose Update"
    trigger:
      - platform: mqtt
        topic: "composeupdater/update/composition/restart/done"
        value_template: "{{ value_json.composeFile }}"
    action:
      - service: notify.telegram_bot
        data:
          message: "Docker images updated: {{ trigger.payload_json.composeFile }}"

Read more about how to set up the MQTT⁠ and Telegram⁠ integrations in Home Assistant.

⁠License

GNU General Public License v3.0

Docker® is a trademark of Docker, Inc.

This project is not affiliated with Docker, Inc.