Best way to upgrade this Docker install!


I have an HA installation. Rather than attempt to describe it, here is the config
System Health

version: core-2021.11.4
installation_type: Home Assistant Container
dev: false
hassio: false
docker: true
user: root
virtualenv: false
python_version: 3.9.7
os_name: Linux
os_version: 5.10.78-4.ph4-esx
arch: x86_64
timezone: Europe/London

If I was using words I’d say it’s a Photon linux VM on ESXi with a docker installation of Home Assistant. I am neither a unix, docker or HA expert so would really appreciate the input of experts here.

My question is how best to upgrade HA from here! I installed it 8 months ago and don’t get any of the “check for updates” features. Now I’ve got a new Ecovac which requires a later version to get the integration working.

I can see from Package home-assistant · GitHub that I could pull a new container. Not sure I really want this latest development version docker pull Package home-assistant · GitHub

What are the steps I’d need to take to backup my setup, do the upgrade and get the existing config all back in? Thanks in advance for all your pointers.

First thing you may want to do is review the breaking changes that occurred from 2021.11.4 to the latest 2022.8. Then I think performing a backup of your configuration directory. I think there is a hacs tool that you can use to backup your system.

1 Like

Very important

Added to that, you could possibly setup a ‘dev’ container with a copy of the config folder and upgrade that to see what will/not be working…this is what I do to avoid situations where I cannot downgrade afterwards (or lose data)

1 Like

When you pull a version from GitHub, you can pick a specific version if there’s one in particular you want after reading through all the breaking changes.
docker pull can be docker pull as an example.

I also recommend making a copy of your entire HA docker folder, but only after you change it all to Read/Write permission as root, so you catch all the hidden files.
Maybe this isn’t necessary, but using Manjaro Linux I could never get some files to copy otherwise.

1 Like

I’m going to basically summarize all of the excellent advice already here:

  1. you need to have access to the HA Config folder and the ability to copy the entire thing, including the hidden .storage folder/files, to a secure location.

  2. read the breaking changes between 2021.11.4 and 2021.12.x so you are prepared to fix them if any impact you.

  3. Do you have access (or can you re-create) your Docker run command that you used to install HA up to your existing version? If yes then it’s just as easy to remove the existing container. BUT leave all of your config files intact in their current location. Just “rm” the container. Then re-add the container by selecting the desired HA image as described above by adding the version to the end of the run command - homeassistant/home-assistant:2021.12.0 (but it’s best to find the latest patch version to add to the end but I don’t know what that is so if the latest in that month was 3 it would be homeassistant/home-assistant:2021.12.3).

  4. if you don’t have that info then you can do as advised above and stop the existing container, pull the desired image version and restart the container.

  5. then deal with any breaking changes.

  6. repeat the above steps this for every month until you get current.

  7. try to stay up to date so that you don’t have to do this again later. :wink:

1 Like

Thanks all. Really appreciate these tips.

@finity So are you recommending doing monthly steps as a way of making the breaking changes “bite size” or because there is a fundamental reason I can’t just jump straight to the latest version and sort out everything that’s broken in a single clean-up?

I think I have my notes here from when I did the initial install (#3). I’ve been regularly tar-ing the HA folders and moving the tar off the VM so I’m good for #1.

And completely agree with #7! It’s all the chat about breaking changes that kinda make me back off doing the upgrades!

When upgrading., the new functionality may base itself on assuming a previous one. e.g. there have been database improvements and I would not be sure how many versions backwards-compatible these are.
As per my earlier comment, you can quite easily create a secondary setup/copy and try it out to go straight to the newest one.

1 Like

So given that the config and the database are stored at the unix level, and we’re not touching those as part of the docker upgrade process, will the database get upgraded upon the start of the incremental HA version on the docker side?

why do you think they are not touched? Config contains a folder .storage and a sqlite database too (unless you use e.g. mariadb). Recently there were some changes to the db and they did change that. I am not sure if the upgrade script apply to all versions, you may need to bring it to an in-between version. As I upgrade bi-monthly I cannot be more specific on possible issues with larger version leaps…hence…copy it and try it out, it may work from scratch

1 Like

Yes, the db is being touched.

it gets upgraded as needed for the version of HA.

the config files themselves don’t get modified.

yes. it’s way easier doing it that way and there is no downside.

if there is no breaking change that affects your system then it’s a matter of a few clicks and a minute or two to move to the next version. If there are then you will need to fix them either way.

It’s really up to you tho. If you feel froggy then just do it as you see fit.

But you’ll have to deal with those breaking changes eventually anyway (see the current discussion as an example :wink:) so you might a well just get them out of the way once a month instead of all at once.

And if you are worried about unintentional breaking changes then just wait for a few point releases to update. it’s what I do. I still haven’t updated to 2022.8 yet but will soon.


Right!! Here goes…


I run docker with watchtower. As soon as a new release is pushed, watchtower pulls it down. That keeps me accountable to ensuring I read the breaking changes, the benefit is I am always on the latest build.
Honestly the only real issue I have had over the past year was with the MQTT change recently, and a ZHA one . For the most part I get the latest update and everything works as expected.

1 Like