Docker, 4 versions of HA, I'm gonna need some help

I’m looking to improve my home automation system, and to improve the machine it’s running on.

Currently I’m running Domoticz on an RPi. While Domoticz is a nice bit of software, the Dashboard and Devices tabs just aren’t customizable enough for me. To add on to that, I have some small stability issues with it, and I’ve seen others that know a lot more about home automation move over to HA, so maybe it’s time to give it a try.

I want to be in a state where I run docker on a RPi, with containers for everything I have running. Currently, I have multiple services trying to use (for example) port 80. While this can be changed in the configuration (and I have, of course), this setting always reverts after an update. So after every update, I have to remember to change the configuration file again, or I’m going to be very confused why some of my things don’t work. As I understand it, this should be a lot easier to handle with Docker.

For clarity: currently I’m testing things with Docker on a Win10 machine. The final install should be on an RPi.

I’ve tried all night to wrap my head around what to do with HA. As I understand it, there are 4 versions:

  1. One where you basically get a prebuilt image to run on (for example) an RPi,
  2. one that runs in a Docker container,
  3. one you can install on an existing machine,
  4. and one I don’t fully understand.

Looking at that list, you’d say it’s an easy choice: go with the one that runs in the docker container. I did, and like many people I quickly found out that there’s no add-ons in that mode. Having looked through a few tutorials, it feels like add-ons are pretty much a must when using HA, so simply running the Docker container doesn’t seem to be an option for me. Or is it? I’ve also seen things about installing add-ons manually, but I can’t find anything conclusive.

Option 1 doesn’t seem to be an option for me, since I want to use the RPi for multiple things, not just running HA. I think you can’t use the OS version inside Docker, since it uses Docker itself, but on the other hand, Docker inside Docker seems to be officially supported?

So it looks like option 3 would be my only option. Create a Ubuntu Docker container, and install that version there. Well, of course I looked at that, but that seems to be a highly specialized and also device-specific process. Probably nothing I can’t do, but before I spend hours upon hours on trying to understand it, it would be nice to know if there are better options.

Option 4 just confuses me, is it a “lite” version of HA or something like that?

I guess topics like this pop up constantly, and most experienced users are completely sick of them, so I apologize in advance, but after spending so much time on trying to understand it (it’s been a couple of years since first trying), I could really use some help.

1 Like

Add-ons are basically tweaked docker containers in and of themselves. Pretty much everything you can find as an add-on, you can also find as a docker container. The main benefit to HA Supervised (#1), is that many of the add-ons also integrate into the HA UI. For people like me, that’s not a big deal, so I run HA Core (#2 (docker container standalone)) with all my other services spread out on various servers across my network. On my main HA machine, I only run HA Core, Zigbee2MQTT, Zwavejs2MQTT, and a few other “IOT” type services. I don’t need any of them to be add-ons because in reality, I actually do very little in the HA interface.

Here’s the thing that many people don’t seem to realize: When you install HA and various add-ons on a rPi, you’re dealing with a constrained system. A rPi4 8GB is still only an 8GB machine with a quad core, small processor. There is a finite amount of computing power there and 99% of the time when people say HA is slow or their devices are responding slowly, it’s due to them running every add-on under the sun on a single board computer. I’m not saying DON’T run it on a rPi, but make sure that you plan for the system that you are installing on.

In your case, I’d go with #2. Install Docker on a rPi then pull the latest HA image and run that. If you find that doesn’t work for you, blow the rPi away and install HA Supervised. You can back up your /config directory from HA Core (#2) and transfer it over to HA Supervised and pretty much everything will work the same.

1 Like

Not true, however if you are using a supervised version of HA, you loose large amounts of direct control since the supervisor is now doing that work, and the way of doing things without addons suddenly becomes very difficult.

In most cases the addons are docker containers with plug and play preconfiguration to be used with supervised HA, for example an MQTT broker. However if you are using something like Ubuntu with HA running in docker, you can just do a apt install mosquitto and then edit the config file yourself, and it is functionally identical to installing the addon.

1 Like

I’ve seen this pop up a few times before, why does HA require so many resources? Like I mentioned, I’m used to Domoticz, which runs on a RPi 2 with 1GB of ram flawlessly (well, performance-wise at least). What’s so different about HA?
For clarity, I plan on running HA on at least a RPi 3B, potentially a RPi4, definitely not the RPi2.

Maybe I’m misunderstanding what add-ons are. I’ve searched for the difference between add-ons and integrations before, but never found a decent answer. For example, on the HA add-ons page MQTT is mentioned as an addon, but it also shows up as an integration. Let me see if I’m now understanding this correctly:

  • An add-on actually installs something which you can use in HA
  • An integration only connects something that’s already installed with HA

If that’s the case, add-ons sure sound a lot less like a requirement than I thought they were, and sounds a lot more like just a “nice-to-have”.

This seems to confirm my suspicions above. In that case, I’d actually prefer not using add-ons. However, in case I change my mind later on, is there a place where you can browse the add-ons, and can see how to install them manually? I tried looking in the Docker Hub for some add-ons, but I couldn’t find them there.

Thanks for the suggestion, I think this is the way I’m gonna go, or at least try. It seems to make the most sense.

1 Like

Right on the first one, not quite on the second.

In the case of MQTT, the integration simply allows you to connect to an MQTT broker, which cab be local, remote, or even not under your control. The MQTT addon runs a local broker in a container.

An integration is some method of using a device or service within HA. This can be a “native” integration, local or cloud, and the code to use it is already part of HA. It can also be a custom component, which you load into HA, in order to integrate something that HA does not support out of the box.


HA in and of itself is actually fairly lightweight. As in, the core install and frontend are both mostly resource friendly. However, the way that HA Supervised allows and manages add-ons (containers) is with docker and because those containers run on the same machine, you see resource usage rise quickly. As I said, many people don’t understand that all these add-ons are really just docker containers rather than “true” add-ons and never take into account why their small, 2GB rPi4 starts struggling with their HA install running over a dozen different ‘add-ons’.

The fact that HA even supports resource-hungry apps like InfluxDB and MySQL as containers on the same instance has always boggled my mind. But, I get that it’s for “ease-of-use” for people that aren’t necessarily “IT” folks.

That’s partially correct. Add-ons are basically small servers (for lack of a better term) and integrations are the pieces that allow you to integrate different functionality into HA.

Taking MQTT as an example, you can install mosquitto (or any other MQTT server) anywhere and still use the integration to connect to it. This is my integration connecting to my homeserver MQTT cluster:

1 Like

I run hass on docker and so far have found an already built container on dockerhub equivalent to every addon I needed. And dockerfiles are just a list of commands that can be easily customized if you need to.

There are also a lot of things I think people run as an addon in hass “just because” and there is little value to controlling or monitoring it through HASS. That’s just the bug of automation though, I do it too, go through the effort of adding something only to find out it adds complexity/dependencies and I don’t look at it or use it in automatios. So you can just run those things in a separate container and just hit a different URL to use it.

The more stuff you run in HASS the more likelihood something will break. And the more data going into the DB, logs, etc. Separate containers can be upgraded/rolled back separately and are often provided directly by project managing the software.

As for you docker port issue if your port mappings are getting lost something like portainer or docker-compose may help manage your docker configs. (Personally I use ansible).


I think it’s just that I didn’t quite phrase the second part correctly (it even confused me when I read it back just now). A better phrasing would have been “An integration is just a connection between HA and something that’s already installed somewhere”, which seems to be the case if I look at your replies.

So the issue is more that every add-on runs on a separate “system”, so even though Docker “systems” are pretty lightweight compared to say VMs, it still starts to bog down quite quickly. That makes sense, I wouldn’t even dream of running a VM on an RPi, so I guess running more than a couple of Docker containers would be just as insane.

Thanks for all the clear feedback and advice guys, this is really helping me understand how HA works, and how I can use it.

1 Like

Fair statement except that pretty much anything now-a-days can be put into a docker container… Things like database engines, which benefit from and typically consume a lot of resources, can run in docker containers and on a constrained system like a single board computer (rPi, oDroid, etc), they can easily be overwhelmed by said containers if not tuned properly.

For instance, while MariaDB has no stated minimum system requirements it typically allocates ~512MB of RAM during startup. Then, when the InnoDB engine loads, by default, it uses another 128MB of RAM for the buffer pool. On a rPi with 2GB of RAM, you’ve already eaten 35%-45% of your available RAM. For a single database system, that’s typically OK until you start loading other containers.

1 Like

Al right, I’ve been playing with HA for a bit now. So far, I’m really liking it, but I’m still running into the “issue” of missing some add-ons. I understand that everything add-ons do can be done manually as well, but it would be nice to not have to remember a specific port to get some functionality, and just be able to have a button in the HA UI.

So, let’s take the text editor (formerly configurator if I’ve understood correctly) as an example. I know it’s not required, and there are many other (even better) ways to handle configuration file etc. editing, but it’s just a simple example I’d like to try.


  • Text editor (/configurator) button on the left side of the HA UI, near the Overview, Map, etc. buttons.
  • Functioning text editor when I click on that button

I tried:
I looked at this GitHub repo, which promises an editor comparable to what’s normally available as an add-on, but I don’t see any mention about integrating it in the UI. As far as I understand it, it’s just a completely separate piece of software that can be accessed through a browser, but does not in any way integrate with the HA UI.

So just to clarify: Is it possible to create exactly the same experience as provided by add-ons (including the button in the HA UI) by manually installing something, or is it only possible to create a (very) similar experience, without any direct integration into the HA UI?

The short answer is no. The longer answer is ish. :slight_smile:

So, for code/config editing, there is the excellent code-server container ( and run that on the same server you are running HA on. From there, use the iFrame panel to host it: I do this very thing and have them (HA and code-server) setup in the same docker-compose.yml mostly because I don’t want to have to expose my HA filesystem as NFS. :slight_smile:

Core users will never have the same experience that Supervised users do. For some of us, that’s fine (myself, I make HEAVY use of bookmarks), but for others, not so much.


The iframe integration is pretty much exactly what I was looking for, thank you!

Do you maybe also know if it’s possible to reorder / remove the default entries in the sidebar that is persistent? I found this merged PR, but that seems to be a local setting, i.e. stored in the browser, and doesn’t survive logging out/in.

1 Like

Yup! is what you are looking for. Load it in HACS and follow the instructions on github. IIRC, it only applies to the default panels though (map, dev tools, etc).

1 Like

That indeed looks to be exactly what I’m after, and it even seems to work for custom panels. Thanks again!

1 Like

I understand your confusion, because you will see different terminology depending on which document you read or how old the forum post is, and add to that the confusion or personal interpretation of the forum poster and the chaos is complete.

This is my take on the different install options, based on the install doc, glossary, and my own confusion:
(Also refer to the Compare Installation Methods table at the bottom of the Install doc)

  1. Home Assistant Operating System
    You flash your storage with an image that is a package consisting of:

    • the OS, “Home Assistant OS” (also referred to as HassOS)
    • the HA “application”. The app in this case consists of the full suite of HA components,
      namely Core (Home Assistant), Supervisor, Audio, and other components of which the functionality is not quite clear (DNS, CLI, Multicast, Observer). Installing the app in this way is referred to as “Home Assistant Supervised”, or a supervised install.
      These components run in Docker containers.

    You get a locked down environment where you have limited access to the OS, can’t run your own containers, and are basically restricted to whatever HA has to offer.

    Recommended for people with no knowledge of or interest to fiddle around with the OS, and/or have no need to add any functionality that is not covered by the HA ecosystem.

  2. Home Assistant Container
    You run the Core container (Home Assistant) in Docker. You only have this one container, not the HA Supervisor or any of the other components mentioned under (1).

    You get limited HA functionality, as you can’t load any add-ons. There are also no auto updates, or checks for new versions. You do have full access to the OS, and can manage your containers as you like.

    Not quite sure who’d want to do it this way.

  3. Home Assistant Supervised
    (Yep, the same name is used for how HA itself is installed and also for how it is deployed w.r.t. the underlying OS.)

    • You install the OS. On a RPi that would be Debian.
    • Then you install “Home Assistant Supervised” ( the full suite of HA components).

    And you get

    1. Full access to the OS.
    2. All features of Home Assistant. Ability to install add-ons, version checks and auto updates of certain components, etc.
    3. Ability to manage your Docker environment and add new containers to your heart’s content.


  4. Home Assistant Core
    No idea.

When it comes to installing “HA Supervised” on Debian (nr 3 above), you could consider to use the IOTstack setup to get you going. It’s basically as simple as flashing Debian to your SD/SSD, get IOTstack from Github, select the stack of containers you want to run from its menu, wait for Docker to be installed and the chosen images to be created, do some app configuration, and you’re off to the races!

Edit: Removed wrong reference to HACS.

That is indeed exactly what happened. I also noticed that most of the HA documentation assumes that you know certain things. If you don’t know those things, you’re even stuck with the documentation.

I’ve been running my test setup this way, and so far I can’t really complain, but on the other hand, I’m not that deep into the game yet. It’s harder to get functionality normally provided by add-ons, but not impossible as I’ve noticed.

Is it though? I want to run everything related to HA in one (or as little as possible) Docker containers. As I understand it, the supervised version of HA installs Docker, and creates at least one container (to run HA), and a container for every addon you install. Since I plan on running HA on an RPi, I’m not sure this is the best way to go about it. I’ve also seen that docker inside docker is, although officially supported, questionable?

In theory I agree with you: If the host machine is powerful enough, the supervised install is the best. You get full control over everything, and the most options. If it’s the right choice in my situation, I’m not so sure about. Your post definitely makes me reconsider it though.

You should do some kind of capacity planning, see how you compare to others who host HA on a RPI. And of course ignore the outliers, guys who scream their heads off because the Pi is so slow. So many things can influence performance, like are they (still) running on SD cards, or are they using a SSD?

Maybe a good question to start would be how many integrations you have, or plan to have in future. “In future” is relative though, because with Moore’s Law you will upgrade your hardware at some point anyway.
But you must see it in perspective… controlling lights that you switch on when it gets dark and off when you go to bed, or a garage door that triggers twice a day (or maybe more after Corona), pushes up the integration count, but does not exactly count as a heavy load.

Be critical of what you really need, and discard the rest. Have a look here for an analytical approach to include/exclude sensors from the database.

Below is the list of HA-related containers that are part of the supervised install:
(I removed some columns that are not adding value here)

docker ps
IMAGE                                               NAMES
homeassistant/armv7-hassio-multicast:3              hassio_multicast
homeassistant/armv7-hassio-cli:2021.03.0            hassio_cli
homeassistant/armv7-hassio-audio:2021.02.1          hassio_audio
homeassistant/armv7-hassio-dns:2021.01.0            hassio_dns
homeassistant/raspberrypi4-homeassistant:2021.3.4   homeassistant
homeassistant/armv7-hassio-supervisor               hassio_supervisor
homeassistant/armv7-hassio-observer:2020.10.1       hassio_observer

Back to the install question…

You will definitely need MQTT, and most likely Node-Red. Let’s just start with these two for now. You will either have to load them as add-ons within HA, or else run them as containers outside HA. Both options are perfectly acceptable (I run them outside). So whether you choose install method 1, 2, or 3, the net effect may be exactly the same - they run in a container each.
That raises the next question, convenience versus flexibility. Option 1 offers convenience but no flexibility - you can only do it one way (add-on), and can only use what is available. Option 2 you can only run them outside HA, because it does not support add-ons. (any other options?). With option 3 you can choose whether you want to run them as HA add-on or as container managed outside HA. With 2 and 3 you have the ability to grow, to add additional containers as your needs change. As example, I now wanted to host my own Mumble (Murmer) server as part of a VOIP intercom setup. I had the freedom to either run it in a container, or install the service directly on the Debian host. With option 1 you’re screwed.

Lot’s of people. I’ve even heard that many of the developers use this install method.

I’m using it right now for two installs of HA - one is my production system and another I do some testing on.

Definitely not true. I use HACS all the time.

You say that like it’s a bad thing. I think that’s a positive (see below). And besides there’s nothing to auto update. The only thing in HAOS or HA Supervised that auto updates is the supervisor (unless add-ons auto update? I don’t use them…).

I personally despise auto updating anything. if something breaks then I at least have an idea why since I just did an update so it’s a good starting point to troubleshoot.

I get notified immediately as soon as there’s a new version so that’s not an issue either.

Then I update at my leisure with literally two clicks by using Portainer to manage my Docker containers.

Maybe but definitely not definitely.

If you don’t use any wifi based devices then MQTT isn’t needed.

And if you use ESPHome in API mode you don’t need it either.

Again not likely at all.

I’ve used HA for over 3 years (almost 4) and I dabbled in NR for about 15 minutes and never saw the use for it. I’ve been able to do anything I want in HA using automations aside from a couple Appdaemon apps.

Some people love it, some (most?) don’t.

This is the very basic install of HA directly onto the host OS in a python virtual environment. It’s the exact same functionality as HA Container except there is no docker involved in running HA.

It’s what everybody ran before there was hassio (now renamed to HA OS).

That won’t be possible.

You can’t run “docker in HA”. It really doesn’t even make sense to think of it like that.

HA is an application. You can run it in a docker container or directly on the OS. It isn’t OS in itself so you can’t run docker in it.

Docker is an application that allows you to run applications in containers.

When you run HAOS you are installing an OS (hence the name) and that automatically installs docker and then automatically installs HA (the application) in a container along with all of the other containers needed to run HA Supervised as noted above.

So even with HAOS you aren’t running docker in HA. You are running HA in docker which is running on HA OS.

No matter how you install HA everyone always gets the same underlying HA. The only difference is if you run HAOS or HA Supervised you get the extra functionality of the supervisor which allows you to do some additional stuff (add-ons, snapshots, one clock updates are the ones that come to mind.

But there are some downsides to the supervised install. The biggest is that it dose automatic updates of the supervisor with no user control at all. And it doesn’t always go well. THere have been a few times people have woken up to a dead HA because of a failed supervisor update.


Where did you get the idea I’d want to do that? I want to run HA in Docker, and try to keep the number of containers related to HA as low as possible.

Based on this:

and this:

If I misunderstood then my bad.