Intro

Make sure to backup your Home Assistant install first!

Also, it’s a good idea (mandatory, I’d say) to check the Release Notes before upgrading. That way you can prepare for any upcoming changes, especially the breaking type.

By the way, this process is the same for updating other Docker containers, like our add-ons.

Home Assistant 2022.8.7
HA 2022.8.7 - before update

Get the latest version

Upgrading a Docker container using Docker-compose involves pulling the latest version of the container’s image and re-running docker-compose to rebuild the container using that image.

docker-compose pull homeassistant
docker-compose up -d
Docker output
Pulling update image via Docker

Containers with dependencies on the upgraded container will be rebuild as well.

Home Assistant 2022.9.1
HA 2022.9.1 - after update

Version sensor

Don’t feel like manually keeping track of when an update is available? Don’t worry, as Home Assistant provides a helpful version integration.

Install the Version integration via Settings > Devices & Services > Add Integration. When asked, choose to track the Docker Hub installation type.
Then install the same Version sensor again, but this time select Local Installation.

Home Assistant Version integration
Track updates to Docker image

Once installed, you can check the entities created by this integration. 2 are created by the Docker Hub version: a sensor that displays the latest version on Docker Hub, and a binary_sensor that indicates whether an update is available. And another one displays the version we currently have installed (Local Installation).

Home Assistant Version integration dashboard
We’re fully up-to-date :)

Add to dashboard

If you want, you can add these to your Dashboard.

Click the 3 vertically stacked dots at the top-right of your Dashboard. Next click Edit Dasbhoard and Add card. Choose by card type and pick Entities. Finally add the Docker Hub and Docker Hub Update Available entities and optionally pick a title for the card.

Version sensor on Home Assistant Dashboard
Version sensor on Dashboard

When an update is available, you’ll be informed through the Dashboard.

Sensor on Dashboard shows Update available
An update is available

Update notification via Docker-notify

Want to get a notification when any of our containers have an update available?

Docker notify is a free web service that allows you to subscribe to docker image update notifications. Enter your email address, and configure for which Docker images you’d like to get update notifications.

Automated updates

Combine with backup script

If you prefer to have automated updates, you could add the commands to upgrade the container to our backup script. That way you’re always have a backup ready, should the update break your setup.

Edit /opt/homeassistant/homeassistant/backup.sh and edit the script at the end or replace it with the following script:

#!/bin/bash
readonly SOURCE_DIR="/opt/homeassistant/config"
readonly BACKUP_DIR="/mnt/backup/homeassistant"
readonly BACKUP_PATH="${BACKUP_DIR}/$(date '+%F')"
readonly LATEST_LINK="${BACKUP_DIR}/latest"

mkdir -p "${BACKUP_DIR}"

docker stop homeassistant

rsync -a --delete \
  "${SOURCE_DIR}/" \
  --link-dest "${LATEST_LINK}" \
  "${BACKUP_PATH}"

rm -rf "${LATEST_LINK}"
ln -s "${BACKUP_PATH}" "${LATEST_LINK}"

#docker start homeassistant
docker-compose pull homeassistant
docker-compose up -d

Alternatively, if you don’t like going greenfield, you could keep the backup and upgrade scripts separated. Through our previous cron job, the backup will run every Saturday. Add a cron job to run the upgrade script just before our safety net.

# sudo nano /opt/homeassistant/homeassistant/upgrade.sh

#!/bin/bash
docker-compose pull homeassistant
docker-compose up -d

# sudo chmod u+x /opt/homeassistant/homeassistant/upgrade.sh
# sudo crontab -e
30 23 * * 6 /opt/homeassistant/homeassistant/backup.sh > /dev/null
45 23 * * 6 /opt/homeassistant/homeassistant/upgrade.sh > /dev/null
55 23 * * 6 docker start homeassistant > /dev/null

Watchtower

A popular solution for automated Docker container updates is using Watchtower.

Watchtower runs as a Docker container as well. It will keep track of all your containers and will automatically pull the latest image for your container and gently restart the container with the same configuration.

Do note that this means a container will be upgraded as soon as a new image comes out. This means you’ll be able to run an evergreen setup but any errors in an upgrade will immediately impact your environment.

To setup Watchtower, you add its config to your docker-compose.yaml and run docker-compose up -d.

version: "3"
services:
  [...]
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
Watchtower logo
Watchtower

Don’t want to automatically update certain containers but get notifications about available updates instead? Add the label com.centurylinklabs.watchtower.monitor-only=true to those containers.
For example:

services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    labels:
      - "com.centurylinklabs.watchtower.monitor-only=true"
    [...]

Make sure you set up notifications if you do so, otherwise you’ll miss out on updates.

Next steps

Using automated back-ups and knowing how to upgrade our Home Assistant Container and our add-ons, our system has become a lot more future-proof.

In the following posts I’ll discuss installing ESPHome and Zigbee2MQTT containers.

Got any other Home Assistant add-ons you’d like me to touch upon? Let me know via Twitter.