Confused by the setup guide

I have been reading the installation instructions and am not understanding what this is looking for…


the layout of this page is horrible and confusing

The developers have bundled everything into one package called “Home Assistant Operating System” for the bulk of people with no experience managing Linux or containers. It includes the operating system, supervisor, and HA container in one clean package. Find the download link here for whatever hardware platform you plan to use:

that is that page that links to the page i linked to… it doesnt explain things

Nevermind… this is just HORRIBLE UI on that page… its not clear that i reached the end of the setup and i thought it was prompting me to do the next section which instead is a different method for installing which it why i was so profoundly confused…

1 Like

I agree about the confusion. My first HA install attempt was in a Docker container last month, just to find out that the Supervisor function only comes with the full Home Assistant Operating System install. Glad that I was only in about an hour or so before I scrapped the Docker container and installed the full OS package…

There is a link to suggest improvements at the bottom of every documentation page. Please do use this.

Developers and seasoned users may be too familiar with the process to see the issues you, as a new user, had.


In my case, the information is embarrassingly all on the /installation/ page…if you read the entire thing! I came in from a third-party web how-to, providing directions for installing the Docker container on my NAS. The third-party page didn’t explain the limitations of that install method, or that basic functions like the Supervisor menu would not be present.

Another issue for people just coming in now is the apparent re-brand from hassio to haos. There are a lot of third-party pages referring to with links, and cause confusion when trying to follow their directions.

I’m going to submit a suggestion to the link on the bottom of the /installation/ page to make the first step choosing your installation method. Move the methods table up from the bottom, and stress that OS is the best choice for a full install. Then the second step is to choose a platform, and the third step is to install HA based on the method and platform chosen…

This sort of comment comes up a lot, and I admit to feeling the same frustration at times.

What I don’t have is a good solution. Sure, a user can click and suggest improvements. But that only works after a poorly-written document has been published.

Yes, this is a volunteer effort and you can’t make demands of the developers as if they were paid employees of a software development team. Fair enough.

On the other hand, there are procedures which the developers are forced to follow if they want their code to be included in the product. I wonder if there’s a way to insert some sort of documentation check in there somewhere.

I’m not sure what that would look like. Maybe there could be a volunteer team who would review the documentation for the change, and research how it impacts other documents which reference or have examples containing things which were changed.

Developers are going to hate me for suggesting this. There’s no fun in documenting things. Believe me, I’ve been on both sides of this argument. Still, pretending we don’t have a problem, in the face of frequent user complaints, is not really honest.

1 Like

Unless you get involved in changing it to a form that’s understandable to you, it’s unlikely anyone else will. Why? Because the majority of users (tens of thousands) who have installed Home Assistant OS have done so on an RPI4 (using the same instructions that you dislike).

A similar problem is new users who only skim the documentation or use outdated third-party tutorials or have weak reading skills or are easily frustrated. Pretending that doesn’t exist isn’t honest either.

1 Like

I could write the proverbial book about managing volunteers in a volunteer organization! The first chapter is never criticizing another volunteer’s work…unless you are 100% ready to do that task yourself.

With that said, there is an “edit” link at the bottom of the page that I can apparently use. As a newbie to Home Assistant (who has worked for 35+ years in IT and is no stranger to other home automation platforms), I feel hesitant to actually submit the edits myself right now.

I do have some professional experience with technical writing and documentation, so I may submit a re-write of that page at some point in the future. Surely the project leaders would rather accept that than Python code submissions from me!!! :slightly_smiling_face:

1 Like

Agreed. It goes both ways! I, too, followed the initial instructions and got everything running. I did have a problem understanding one step, but with help from this forum I figured it out and posted what I’d found for others who might have the same issue. That thread turned out to be pretty popular.

Interesting chart you posted, too. So often I see negative comments about using an RPi for HA. Good to know I’m not alone. Sure, it’s not for everyone, but it does all I ask of it, barely making a dent in the available CPU and memory.