Addons for Docker installation

Having Home Assistant running in a Docker container has many benefits: one can just stop the old version and start a new one instantly, all software is self-contained and immutable, so it can never be “corrupted”, many operating systems and even appliances (like NAS devices) now are able to run Docker containers so you can just run HA on a device that in your home network anyway, it is impossible to have leftover processes when you restart HA in case of any problems, …

However, running HA in a Docker container still comes with a major downside - you only get HA Core and no way to install and manage addons. The UI does not even suggest that such a thing exists at all when you are running in Docker. So you first need to discover that such a thing as addons even exist, then you need to find addon lists or registries to figure out if you need any of them and then you need to figure out manually how to install and start each of them.

I believe we can do better and most of the functionality is in HA already.

How about we make use of the Docker Compose functionality and plug the HA Addon Store into that if running in a Docker container installation? All user-facing Addon Store functionality would work just as it does in HA OS or HA Supervised installation, but the information about what Docker containers need to be started for which addon and with which settings would be simply written into a “docker-compose.yml” file in the config folder (including an entry for the HA Core itself). It would then be up to the user to use that file from their base OS to restart the whole set of containers when they add/remove or upgrade addons via the Addon Store.

This should not be too complex technically to implement withing the existing code, it would make addons discoverable for Docker installation users and it would allow people to easily install, use and maintain Docker installations with addons.

Are there any blockers to this idea?

Installing Home Assistant Container is a choice; it employs docker and has a backup feature but doesn’t contain an operating system, Supervisor, or support for the Add-on ecosystem.

Home Assistant Supervised employs docker and has a backup feature plus it contains Supervisor and support for the Add-on ecosystem.

Home Assistant OS contains everything found in Home Assistant Supervised edition plus an operating system.

See: Compare installation methods

Users who choose to install Home Assistant Container do so usually because they are completely comfortable with managing a docker-based system. Therefore they can easily install, for example, Mosquitto as a standard docker container rather than its Add-on equivalent.


The key reason for me for choosing a Container installation is that I want to also be doing something else on the computer that is running HA. For example, running the HA on my TerraMaster NAS device. It is impossible to run HA OS on that or HA Supervised. Same when running HA inside a TrueNAS installation or on any other device.

And even when installing on a custom PC … well, I want to also run something else on it, not just HA, so HA OS is out. And the HA Supervised also had to be disqualified because it demands to only use Debian (no Ubuntu, no Arch, no any other Linux) and then it also messes up the system quite a bit, for example completely disabling cgroupsv2 infrastructure that modern systemd systems depend on.

Docker container installation is the easiest and requires the least investment or support from the surrounding environment.

As a user I do not even have any idea from HA interface or documentation that a “Mosquitto” addon is even available. Do I need it? What does it do? How to install it? How to start it? How to connect it to HA? The Addon Store has all those questions solved. The only missing part is writing this information down into an easily usable, ideally machine-readable form, such as docker-compose.yaml


Yes there are many. Addons are not just docker containers. Here’s a list of all the configuration options addon developers have available to them that supervisor makes work. As you can see there are quite a lot.

In addition supervisor has its own API for obtaining and updating host settings that addons can request access to. It also facilitates secure access with home assistant by giving an access token and a passthrough API when the addon requests it. Supervisors current rest API can be found here.

Supervisor also created and manages plugins to ensure things like multicast work properly for addons that make or consume multicast services. And DNS and communication between the containers works even for ones on the host network.

Then there’s apparmor. Addons can provide custom apparmor profiles which supervisor loads and applies on the fly. There’s device access, supervisor handles cgroup management and sets up device access for addons. Etc.

Honestly this is a very short list I typed out off the top of my head on my phone. A detailed deep dive would be much longer. Many of these things have no straightforward docker compose equivalent.

If you are comfortable in docker compose and scripting in Linux then feel free to choose container. It is a fully supported approach but you will need to do a lot of work yourself. But on the other hand you get full control and can run anything you want on your machine.

If you want addons then you need supervisor. And that means either the host machine or a VM must be dedicated to supervisor. It will manage the entire thing and the only containers that can be added are addons. Supervisor is far too deeply ingrained into the host to be able to treat it like a normal Linux system alongside it. It needs to be treated like an appliance.


Frankly, what you are describing is saying exact opposite of easy for someone to replicate on their own. Users choosing to install HA with Docker choose it … because that is far easier to do. It is literally a single command on any system that supports Docker and does not require dedicating a whole hardware box just to running HA. Everyone is using Docker now and starting new software in Docker is the first thing people will try. It is not something that only very advanced users will try. Just the opposite.

Some addons make no sense in a system where other things are happily running alongside HA, such as file servers and databases and what not, especially if they are just there to start those services and have no specific benefit to the HA itself.

But being unable to install and use things like deCONZ or Ada or Node-RED is a big downside. Currently there isn’t even any hint that those things are at all available. Never mind any pointers towards installing them and making them run. AFAIK the only way to figure out how to run an addon that I could find is to literally look at the source code on the addon registry. And, from your last comment, even then it might not even work because the addons would be depending on the Supervisor API running?

So “you can run it yourself” is then completely misleading and the real answer is “If you use HA in Docker, then that is all you will ever get - just Core, no addons for you, no Z-Wave or MQTT for you, get a real box and dedicate it fully to HA to get full functionality”. And Docker is just demo mode. At least that would be honest. Even if more and more HA functionality shows up now only as addons and thus become more and more unavailable to all Docker users.

It is ok, if some addons do not work at all or if some addons require from the user some host setting adjustments (which may or may not be possible to do if the host system is a FreeBSD based NAS, for example), but there should be at least a path towards getting at least some addons working in a supported installation system if the addons are becoming more and more important. Running software outside of the container that is going to try to modify host system settings is not a viable solution - in some cases some of the modifications will not be welcome (like disabling cgroupsv2) and in other cases they will simply not be possible. Just running custom software outside Docker might not even be possible.

If the addon is modifying the host - it will not work. IMHO that is a feature. The whole point of having addons in containers is to prevent them modifying the host. Cgroups and apparmor are extra security features, they do not influence functionality. One can give info to the admin how to load and enable them, if they are available in the base system and the admin cares about restricting the services. Network, connection and device/file access could be described with docker compose syntax. Compose also takes care of service names and discovery. In fact, I am pretty amazed that Supervisor is not actually already using Compose to manage addon containers.

In a very real example of running HA as an additional app on a NAS the host system bears only passing resemblance to Debian Linux and there is no way Supervisor would be able to do anything it tries to. And if it does, it might break the NAS functionality along the way, which would be bad.


Nearly all addons repackage existing software. In nearly all cases the maintainers of that software publish an image and some kind of documentation helping you get started. The Mqtt addon everyone uses is mosquitto, the image published by eclipse is here. Node red’s docker guide is here. Zwave js’s pure docker setup guide is here.

Of course this isn’t the entire story. In addition to just setting up the software the addon also makes integration with HA easy. It does this with things like discovery (where an addon tells supervisor what services it provides and HA let’s core know that is available). Or a autoconfiguration of an integration if the service has one (like zwavejs). Or having the maintainer automatically add packages that people typically need and manage the HA config for you if the addon has an HA integration (like node red).

Basically supervisor makes a lot of things easier. None of this stuff is impossible without it it’s just easier with it. There’s a lot of steps to replicate what an addon just does. Some in docker compose, some in the host, some in the config of the containerized service, etc. But to get that easiness you have to let supervisor run your system, that’s the tradeoff.

Fwiw this is why if you look around the forum many many of the people that previously advocated a container or supervised approach have switched to a VM approach. If you use something like proxmox then you can put HAOS in a VM and let it do it’s thing. And then add other isolated vms as needed which you can fully manage.

I think of the ones you mentioned I might agree most with zwave. Since zwavejs is now the HA answer to zwave it does feel like there should be a guide for setting that up linked directly from the container install method. But all the others (Mqtt, node red, etc) I don’t agree. None of them are required. If you figure out you need them due to your particular automation needs then you go seek them out. That could mean looking in an addon store or googling, either way you need to figure out you need them and then follow some instructions.


Correction: The

If you have the requisite skills to install and maintain Home Assistant Container, the same skillset is needed to answer those questions.

If someone doesn’t know how to install a docker container, to provide an additional service (Mosquitto, Node-Red, Caldav server, etc), they probably shouldn’t lean towards using Home Assistant Container.

Honestly, everyone is free to make Feature Requests but the odds of anyone on the development team taking the time to implement this one are low. Their preference is to direct users towards Home Assistant OS. For example, the backup feature recently added to Home Assistant Container wasn’t to make it more feature-complete but to provide users with an easier upgrade path to the OS or Supervised editions.


I believe you have a very fundamental understanding of the differences between Supervised and Container and between add-ons and regular docker containers and how all of the pieces fit.

Add-ons are literally just Docker containers but with a whole lot of stuff added as noted above to make them to be installable and completely managed by the Supervisor. Those same docker containers are still available to you too without running them as an Add-on.

You can literally run pretty much every add-on as a docker container but the difference is that YOU need to configure and maintain it yourself.

Absolutely not at all.

I run zwavejs and mqtt and several other apps that exist as equivalent add-ons as docker containers right now on my HA Container install with no issues.

Most of the time if you are capable of installing HA in standard Docker then you can also figure out that you might need those other apps as the need arises.

It’s pretty much the same way that you know to install an add-on as well. If you realize that you need to run MQTT to get a device working you start investigating how to install it. It’s the same with Zwavejs, Deconz or any other third party app that interfaces with a HA integration.

The user chooses which install method to use to meet their own needs and skill level.

you chose Container (as did I for many of those same reasons that you) and that means no add-ons. BUT by no means does that mean I am in any way limited in any functionality where HA is concerned (especially not “demo mode” whatever that means). It just means I have to configure and run those other apps myself.


And I personally find that HA Supervised is actually more limiting than HA Container because of the restriuctions the Supervisor puts on you.

And if there is no add-on for some app that you need (not every container has an equivalent add-on) then you are still going to have to fall back to installing the app into docker manually - which is way more complicated if you use a strictly Supervised install and pretty much impossible if you use HA OS.


Exactly, came here to say this.

The other big problem with this approach is (at least I would argue) HA container is installable in many more types of setups compared to HA OS which makes this feature request even more difficult to accomplish. Even more variables and even more edge cases.

Also, I’d argue the ease of getting started with “one command from command line” is irrelevant to the features that it should support.

1 Like

Once you know what you need, the big problem is the integration between third part software and HA. Say I figure out that I need Node-RED for that complex automation I want to do. Can I just install Node-RED? Sure, but Node-RED documentation has zero mention of HA. And the HA Node-RED documentation just tells me to click a button in the Addon Store, which I do not have. There is a gaping chasm of missing knowledge that users are faced with just at the point where they have least knowledge about what exactly is required of them.

I would at least have a hope of getting there if there was an Addon Store in my Container HA instance and if, when I pressed the install button, it would tell me “Ok, now you need to start this Docker container with these options along side the HA container, oh and use this kind of default database in your new containers, meanwhile I will add some lines to the HA config to autodiscover that new service that you are adding so it will show up when you are done”. Then I’d have a hope of discovering and figuring out what exactly is needed to get stuff working.

At this point I have two broken parts - a third party server that has no idea what HA is and HA that has no idea there is a third party server it could use somehow. And zero docs on how that is supposed to be connected because everyone that knows already knows and everyone that doesn’t uses the HA OS where that problem simply does not exist as the store/Supervisor autoconfigures it. Oh and also conflicting user stories - with some saying that it all is just trivial, just start containers like you already know how and others saying that it is impossible because the Supervisor API is essential. So who do I believe?


Do you really think that we all started with HA knowing all of this stuff?


The only Linux experience I had when I started was from running Retropie on a Raspberry Pi.

I didn’t even know Docker existed until I saw it mentioned here on the forums as a way to install HA. Before that I ran HA Core in a venv on a RPi.

But I put in the time to actually learn things.

And it’s fine if you don’t want to put in that time. Just use HA OS or Supervised.

But if you want the freedom then that takes putting in the time to research and learn.

Well, apparently you know how at least a little bit since you managed to install HA Container in the first place. We have to assume at least a minimal amount of knowledge at that point. From there you can learn the rest.

I have literally never heard anyone ever say that on the forums. Not that I’ve read everything here but I’ve spent an awful lot of time here over the last 5 years so I could have missed it but if anyone did say that it was likely a newer user who had no idea what they were talking about.

Or maybe it’s a bit of hyperbole/projection on your part. :man_shrugging:

me. :wink:

or any other user who has been here for a bit.

where did you find this documentation? I’ve never seen it.

But it’s not even necessary to use Node-red in HA, either.

I’ve never used it and again I’ve never been limited in my ability to write an automation without it.

1 Like

Read reply 3 in this thread that tells us that it would be impossible for the HA Addon Store to just generate a Docker Compose entry and HA configs for addons because they are “not just docker containers”.

Starting HA in Docker is trivial and also well documented. As long as you have a working Docker installation it is literally one line and that line is provided in the HA documentation. It does not require any knowledge of HA or Docker to do so. It surely does not imply the sudden acquiring of arcane knowledge of how to start Node-RED or deConz in HA-compatible manner and how exactly to tell HA that you have started these things and how HA could then connect to them. A new user would not even know how to see if these thing and the connection is working or not. I have no idea what to expect from HA when Node-RED is fully integrated and working. Why should I, I just found about about its existence days ago?

  • the instructions on the HA side are just to click the button in the Addon Store.

Even a simple hint that for most (?) addons you’d also need to add an integration or a config snipplet to your HA to have HA actually be able use them would go a long way. It is really, really hard as a user in the know to understand what new users have no clue of even not knowing.

I mean, I am a Linux and Python developer with over 20 years of experience. I can (technically) just read the HA, Supervisor and HA OS source code and figure out what it does. But I do not believe that is a great way of approaching new user experience.

1 Like

Again you are confused and mixing concepts.

I never said (and neither did @CentralCommand) that it is impossible to obtain the same functionality for the base app without using the Supervisor API.

He said that it is impossible for the Supervisor to write a docker-compose file to get you the SAME functionality as an add-on because there is A LOT of overhead in an add-on to make the Supervisor functionality available.

BUT at it’s base the add-on is just simply another docker container (with all the overhead added).

You absolutely CAN obtain the same functionality as the add-on base app (but without the supervisor stuff) by installing the base docker image.

And so are most docker containers documented to the same (or similar) level.

most of the images on docker hub have the image documented on how to run it in the same manner as the HA docs do for HA. Or the docs can also be found on the associated github repo for it.

You’re right. HA Container is in no way meant to be for a “new user experience”.

That is what HA OS or Supervisor is for.

You have the option to install those as well.

But you want more freedom. So you chose HA Container.

YOU made the choice. So YOU have to accept the trade-offs that come with that choice.

1 Like

Whole heartedly agree. Hence why there are warnings ensuring new users know that they will have to be Linux experts to use the container install method. Really any method besides HAOS.

Also I’m confused at why you seem to be calling out node red in particular for a couple reasons:

  1. node red is an alternate automation platform. HA comes with its own automation platform. Out of all the addons that one seems like the absolute least likely to get a guide (well I guess AppDaemon is equally unlikely for the same reason). Any time invested in that could be time invested in improving the native automation editor. Makes no sense
  2. it’s honestly one of the easiest ones. NR has extensive documentation. And if you’ve used it at all you know that everything it can do is in it’s pallette. Its not even really a docker compose problem, all you do is install this via pallette manager and follow it’s excellent doc and you’re all set. The addon installs other packages for convenience but they aren’t about HA integration and you can find them all in manage pallette. NR basically is a whole separate thing.
1 Like

At the end of the day, most of the HA addons are just mimicking what someone that is at ease with docker containers and linux would discard as trivial (“SSH & terminal addon” is a fair example). or just already has in place (nginx, letencrypt, …).

I think there is a fundamental contradiction between finding docker trivial and wanting addons :wink:

1 Like

See, the thing is - as a new HA user I have zero clue what Node-RED is, what it is used for and how it is supposed to be used and how it is not supposed to be used. Or deCONZ or Ada or ZwaveJS. All I know is that functionality is added to HA by “integrations”, so when I get said in a user forum that “that thing you want to do is much easier with Node-RED” or “your device will only work via deCONZ”, then first thing that I will go to is to install an integration with the same name. I do not even know what addons do … because it is impossible for me to just install and try them on my HA installation. A user does not want addons a user wants more HA functionality and some of it is locked behind addons.

In some cases this actually works just fine - (I had no need for deCONZ or Zwave, so I just tried that now) the integrations for deCONZ and Zwave JS have a Help button and then in the integration docs there are actual instructions on how to start the required external servers with Docker and how to pair them with HA. That is awesome.

In other cases, like Node-RED, well there is no integration there and the user is lost. The interest is not to “use Node-RED” or learn the Node-RED infrastructure, it is to get more functionality in my HA installation. As you said - there are far better and easier ways to, for example, get SSH/Šamba access or install MariaDB or NGinx server on your computer. People with containers do not need support for that. But for external things that do actually integrate into HA and add to its functionality, there more straightforward documentation or scripted assistance would be welcome.

And to be clear, I do not want to run Supervisor for this to happen. It is not even possible to do so in most setups where HA is run in container. If HA is running in a container, then whatever solution is there for addons must also be run inside a container. Either the same as HA Core or a separate one.

If you are saying that a user can easily get the same functionality on their own, then it must also be possible to generate some combination of docker-compose config, derived Docker containers and HA configs that would also enable the functionality. And then expose them via the same Addon Store interface. Without any Supervisor at all being in the picture.

Or at least a documentation section describing step-by-step how to get a few common addons running and integrated manually. deCONZ and ZWave JS integrations are really close to providing that documentation, so they can just be linked from the main documentation pages. That would be a really easy win. Having a couple more examples for how to install and enable an addon that does not have an integration of the same name readily available would help a lot, including an addon from community, explaining exactly where to find the information about: what extra container needs to be started, with what Docker settings, with what configuration of the server inside and where to find out what settings need to be set in HA. If that is generic enough so that the user can then look at Awesome Home Assistant and apply the same procedure to get (most) other addons working on their own would be a major win for usability and user education.

P.S. That “excellent doc” link opens to an empty page for me, just the headings, no content :smiley:

There’s a node red integration in HACS but overall nodered is a separate automation platform.

I think in general installing things without researching what they are first is ill-advised. For example, some prefer node red but I’ve personally preferred HA automations and never had anything I couldn’t do in those.

At the end of the same seems this is more about better documentation than running addons for a container install which I think is very unlikely to be done by the developers.

To prefer something over something else you first need to try both and thus be able to install both. Addons bring amazing additional functionality to HA. Like Zwave support and voice interaction support and who knows what else. AFAIK the Matter support is also now coming via Addons. That would be pretty important, don’t you think?

It is more about having a viable way to have the Addon Store be there in the container install, including the ability to add community addon sources. Even if all that the “Install” button was doing is pop up manual instructions on what to do for each addon. If addon installation is as easy as some people here are claiming, then there should be no problem pre-generating a viable docker-compose entry for an addon container (possibly using a HA-specific container) that would just work most of the time.

Having read bits of the replies here and coming in as someone who’s first interaction with docker was setting up HA container:

Everything in the docs suggest HA container is an advanced method to choose, and you know from the start add-ons are not an option (well HACS is but that’s different).

Whilst setting up HA in docker is simple for someone who understands docker, docker itself has quite the learning curve so is not the best choice for someone who isn’t prepared to learn the ins and outs of how it works. And that also includes how to use it and extend the functionality of HA.

This is why HAOS and HA supervised exist. I do understand where you’re coming from wanting add-ons but the fact is if you choose HA container you’re expected to take on the role of the supervisor in the other distributions. Expecting to spin it up easily and then hand over control defeats the point of why people that choose docker make that decision.

Plus you can always just use proxmox and have HAOS installed along side debian or Ubuntu running the rest of your docker apps.

I think rather than asking for add-ons/integrations in docker container the preferred option is to get involved in updating the docs or making a guide on the forum that can guide people through setting up docker/docker-compose AND extending functionality. So far in my experience finding those guides and examples as been the difficult part.


Matter has already been confirmed to be shipped as a standard docker container for docker users as well. Again, nothing in an addon that CANT be run in docker as well.

This is still functionally the same as doing it right through docker, after it’s installed you’d still be asking yourself “how do I integrate it with HA?” so I don’t think it solves any issues. The main problem it seems is how to find the answer to that question.