How I Use Home Assistant and Tugtainer for Docker Updates

Updating one Docker container is easy. My Home Assistant setup now spans four Docker hosts and dozens of services, so checking images, recreating containers, watching health checks, and cleaning old images by hand stopped being practical.

I use Tugtainer for the routine work, Home Assistant for reports and persistent notifications, and Codex for the smaller group of services that need a Compose-aware recovery path. The result is one update workflow with two lanes instead of a blind auto-updater.

Why one automatic updater is not enough

Most containers follow the same sequence. Check the configured image tag, pull a changed digest, recreate the service with its existing settings, wait for health, report the result, and remove the old image after success. Tugtainer handles that common path across the estate.

The edge cases matter. A container can start with the wrong command arguments. A healthy service can need more time than the updater allows. Docker can fail while reconnecting a network. The updater itself should not replace its own coordinator halfway through a run. Those cases need more than a green running state.

The routine lane: Tugtainer

The Tugtainer server coordinates policy and reporting. An agent on each Docker host performs the local Docker work. Each container can participate in image checks, automatic updates, or a more controlled review path.

• Check: compare the configured tag’s current digest with the registry.
• Recreate: pull the image and preserve the container’s existing configuration.
• Verify: wait for Docker health and record updated, failed, or rolled-back results.
• Clean: reclaim the unused image only after the replacement succeeds.

Tugtainer follows the tag in Compose. A container pinned to a fixed version stays pinned until I change that source configuration. That separation keeps version decisions in Compose instead of asking the updater to guess.

Home Assistant keeps every result visible

Tugtainer sends its report to a local Home Assistant webhook. The package records the last update time and creates a persistent notification with the full result. Normal updates remain easy to scan. Failed and rolled-back services stay visible until I review them.

trigger:
  - platform: webhook
    webhook_id: !secret tugtainer_updates_webhook
action:
  - service: persistent_notification.create
  - event: tugtainer_available_detected

The package also reads the report. When an Available section appears, Home Assistant fires a review event. A 24-hour cooldown stops repeated checks from opening the same work again. Home Assistant Core stays behind an explicit approval, configuration check, and maintenance window.

The original notification setup is documented in Tugtainer: Automated Docker Updates With Home Assistant Notifications. I also use the same report path for a narrower Home Assistant changelog review workflow.

The exception lane: Compose and service proof

When a routine update fails, Codex starts with the Tugtainer report, container logs, and the real Compose definition. The recovery keeps a rollback image, pulls through Compose, recreates one component at a time, and preserves command arrays, volumes, networks, and health checks from source.

A running container does not prove the application works. Dashy must return its page. Duplicati needs its scheduler and web endpoint. WordPress needs a local response and a working public path. Each important service gets a check that matches what users depend on.

After the service passes those checks, Codex asks Tugtainer to check it again. That clears stale availability data and makes the next Home Assistant report agree with Docker. I use the same controlled path for Tugtainer, its socket proxy, and host agents because the coordinator should not replace itself while it is managing updates.

Build the workflow in this order

1. Make the Docker estate visible so you know which hosts and services you are managing.
2. Automate the routine image check, recreate, health, and cleanup path.
3. Send every result somewhere you already look. I use Home Assistant persistent notifications.
4. Define application-level success for services that need more than Docker health.
5. Reconcile the updater after manual recovery so the next report starts clean.

Home Assistant source

The public implementation lives in config/packages/tugtainer_updates.yaml. The supporting infrastructure dashboard is under config/dashboards/infrastructure. Adapt the webhook secret, event handling, review target, and service checks to your own environment.

Watch the complete walkthrough

The video shows the real multi-host environment, the Tugtainer update path, Home Assistant notifications, rollback examples, and the controlled exception workflow.