Installation Methods & Community Guides Wiki

Blog
1

We recently announced that we wanted to deprecate the generic Home Assistant installer. We discovered that the installation method was more popular than expected and we put that plan on hold.

The feedback to our announcement also included that the preferred installation methods are not well documented and that it’s confusing because there are also so many other installation guides on home-assistant.io, some great, some outdated and no longer correct or even missing.

Today I want to take a step back and take a holistic view of installation methods. What installation methods do we support as a project, and what does supported mean.

State of the documentation

If you look at our documentation, it’s all over the place. Install it in Docker, in a VM, on a NAS or on one of the many Linux distributions.

The reason we have this many guides is that since the start of the Home Assistant website, we have always gladly accepted every contribution to get Home Assistant running on any platform. The more the merrier!

However, in software nothing ever stays the same. All software gets updates to fix bugs, fix security vulnerabilities, improve performance or to add new features. As a software application you need to grow along or else you get stuck with an insecure system.

So as Home Assistant grows and evolves, some of these installation guides became outdated and stopped working. We wouldn’t even know it was broken until a user raised an issue. But when they do, we wouldn’t know how to fix it unless we could get a hold of the original contributor.

This can be frustrating. Any guide on our official website should lead to a working system. A system that not only works today, but also tomorrow. And we have not done a good job at this, for which I want to apologize.

Definition of an “Officially supported installation method”

Today we are introducing a classification between what is “Officially supported” vs “Community supported”. An officially supported installation method in the Home Assistant context means:

“A way of installing and running Home Assistant that is officially supported by the Home Assistant project. It means the installation method is tested and documented in the official documentation. Running Home Assistant using such a supported method, leads to the optimal user experience, now and for the future.”

The Home Assistant team will not prevent you from running Home Assistant using an unofficial method. However, we cannot help with issues that you encounter. We are open for contributions that improve compatibility with a community supported method as long as they do not impact officially supported methods, add a significant amount of code exceptions or future maintenance burden on the Home Assistant development team.

Supported installation methods

These are the four installation methods that are officially supported:

  • Home Assistant Full installation of our all-inclusive home automation system. Best in class home automation is complemented with a UI for configuring your system, making backups and safe updates with automatic rollback.

    This method was previously known as “Hass.io”, and includes our Operating System (HassOS), the Supervisor, and add-ons. It can be run on various single-board computers or in a virtual machine.

  • Home Assistant Container Run just the Home Assistant Core application on a native OCI compatible containerization system (like Docker). It does not provide the full Supervisor experience, and thus does not provide the Supervisor panel and add-ons.

    This method has a new name, and was previously known as “Home Assistant Core on Docker”.

  • Home Assistant Supervised The full Home Assistant experience on a regular Linux operating system. This method was previously known as “Hass.io on generic Linux”, installed on top of, e.g., Debian.

  • Home Assistant Core Run the Home Assistant Core application directly on Python. It does not provide the full Supervisor experience, and thus does not provide the Supervisor panel and add-ons.

As you can see, the Home Assistant Supervised method is here to stay.

What is missing for each of the above-listed are the specific details, e.g., the supported operating systems for a Supervised installation or the supported hardware for a full Home Assistant installation. We hope to have these details available soon.

Community Guides Wiki

Home Assistant is an open-source project and it can be used in any way you want, even if it is not officially supported by the Home Assistant team. We welcome these alternative initiatives and have created a place for our community to provide, share and collectively maintain additional documentation.

We’ve added a new section to our forums called “Community Guides”. Each post will be automatically turned into a wiki article that other members can help maintain and can be discussed right below the article. This section is not just for installation methods, but ANY guide, how-to or tutorial.

We have ported several guides from the official documentation to the community guides. These guides were already marked as “community provided” guides previously, or are targeted towards extremely specific setups.

Final words

Today’s blog post is about bringing some clarity on our stance with the Supervised installation, but at the same time bringing more context to the problems and solutions we are currently working on. Cleaning up and structuring our official documentation is an important first step in this process.

Realizing we have not finished up specific details on each installation method, you might still be wondering if your setup is going to be supported moving forward. These details can be expected soon. We have no intention of preventing Home Assistant to run under community supported methods.

Thanks to the passionate community, you spoke and gave feedback on this. We’ll have more specific details to share in the near future, so stay tuned.

Paulus

This is a companion discussion topic for the original entry at https://www.home-assistant.io/blog/2020/05/26/installation-methods-and-community-guides-wiki/
60 Likes
2

Thanks for the explanations! Appreciate all the great work you guys are doing and for making Home Assistant even more fantastic.

2 Likes
3

I am so happy that the Supervised edition continues to be supported - this gives all the benefits of being able to do custom things on a Debian system, while ALSO being able to run Home Assistant with all the great addons.
You guys absolutely rock!

11 Likes
4

Thank you for clarifying the official installation methods, for assigning the ‘Core on Docker’ version its own (more compact) name, and for retaining the Supervised version.

The new naming scheme helps to distinguish all variants of the ‘flagship’ Home Assistant version (i.e. version available as a disk-image, or VM, containing HassOS for a specific hardware platform). All variants have a qualifier in their name: Core, Container, or Supervised.

I assume renaming ‘Home Assistant Core on Docker’ to ‘Home Assistant Container’ is a very recent development because my 0.110.2 instance still identifies itself using the old moniker.

3 Likes
5

That’s great to hear. I’ve struggled for a while to get my first Home Assistant set up, even though I’m quite tech savvy. If you’ve been into it a bit longer a lot makes more sense, but getting started really isn’t always as easy as some advertise.

I ended up with a Home Assistant Supervised on a generic Linux (Raspbian actually) an that has been running great.

Thanks for clearing up that this is to stay, I honestly thought that was already the case and that the Core (python) install was being deprecated!

Good decision in my book!
Thanks for such an awesome product.

6

The naming was not finalized before the release of 0.110. Will ensure this gets corrected soon.

7 Likes
7

Still seems a bit silly to give the Home Assistant name to something that requires HassOS, but I suppose that ship has sailed.

Glad the docs are getting a much needed face lift :tada:

3 Likes
8

Sounds good. I guess if a particular distro is needed for the supervisord then put it all in a VM?

1 Like
9

Thanks for confirming continued support for supervised !

1 Like
10

Hi there,
Please don’t apology. HA team doesn’t owe anything to us.
We all use this free great piece of geeky thing, you just deserve our ‘merci beaucoup’.
And by the way, thanks for those explanations :+1:

2 Likes
11

Thanks to all involved! This must have been a huge effort in communicating within the team and ironing out the details.

Home Assistant has to be the software project with the strongest community and clearest vision, with a culture of using difficult problems to become even more awsome.

As a non-developer, it is very fascinating to see this software improve at such a fast pace. Thanks everybody for this!

4 Likes
12

Thank you for this clarification. About the Community Guides, why not publish them on the official website in a dedicated section? It’s for the ease of the edition? Who validate the modification?

1 Like
13

There is not a vetting process for wikis in general. The community as a whole will ideally self-regulate information and if abuse pops up it can always be reported to the mods.

1 Like
14

Thank you for the update, continuing generic Linux and all the great work you guys are doing.

This really is a great project with a very nice community. It almost reminds me of the early internet days.

15

Thanks HA.
Long live to supervised on Linux! :tada:

7 Likes
16

Thank you very much for HA Supervised on linux

2 Likes
17

thanks for listening to the users and keeping the Supervised install.

The naming is getting better but since there was a name change involved I still think you could have taken the opportunity to improve things even more.

Since we have a “Container”, “Supervised” and “Core” the thing that we are now calling “Home Assistant” should have been renamed “Home Assistant OS” or something similar since the “OS” part is the only obvious thing that differentiates it from the other “versions” of HA.

Since we all technically run Home Assistant just different versions then keeping the generic “Home Assistant” name for the “OS” version is still going to cause unnecessary confusion.

But at least it’s closer to making sense now than it was before so It’s a step in the right direction.

Thanks for that.

10 Likes
18

Thanks for listening to the community and thanks for the renaming, much clear now

2 Likes
19

This is really great news, thanks a lot for the reconsideration! :tada:

Will you guys unarchive the supervised-installer repository? (this one happens to be left off in a broken state BTW, one of the last few commits introduced a syntax error, I would open an issue there but it’s not possible ATM)

3 Likes
20

Can the Community Guides be added to the top menu?

image
image1094×72 7.04 KB

3 Likes