Installation generic x86 x64: add steps (#29997)

* Installation generic x86: add steps

- to use restore disk image from Ubuntu instead of using Balena Etcher to install HAOS
- Restructure procedures to favor the live Operating System from USB over the Balena Etcher method
- Reason: according to the issue tracker, there seem to be recurring issues with the Balena Etcher method
- Adresses feedback provided in #29684, #28961, and #28706

* fix formatting

* Add notice, fix step numbers

* Apply suggestions from code review

Co-authored-by: Stefan Agner <stefan@agner.ch>

* Apply suggestions from code review

Co-authored-by: Stefan Agner <stefan@agner.ch>

* Fix structure

* Update procedure and screenshots

* Fix formatting

* Small rephrase

* Tweaks

* Fix typo

* Add note to decompress image file if installation fails

- as indicated by #28961

* Apply suggestions from code review

Co-authored-by: Stefan Agner <stefan@agner.ch>

* Update source/_includes/installation/operating_system.md

Co-authored-by: Stefan Agner <stefan@agner.ch>

* Rephrase caution statement

* Apply suggestions from code review

Co-authored-by: Stefan Agner <stefan@agner.ch>

---------

Co-authored-by: Stefan Agner <stefan@agner.ch>
This commit is contained in:
c0ffeeca7 2023-11-28 18:48:00 +01:00 committed by GitHub
parent b4eab1badb
commit 00cfcc4633
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 118 additions and 54 deletions

View File

@ -1,4 +1,4 @@
## Install Home Assistant Operating System
# Install Home Assistant Operating System
{% assign release_url = "https://github.com/home-assistant/operating-system/releases/download" %}
@ -6,17 +6,16 @@
Follow this guide if you want to get started with Home Assistant easily or if you have little to no Linux experience.
{% if page.installation_type == 'odroid' %}
{% if page.installation_type == 'ODROID' %}
### Suggested hardware
## Suggested hardware
We will need a few things to get started with installing Home Assistant. The links below lead to Ameridroid. If youre not in the US, you should be able to find these items in web stores in your country.
You will need a few things to get started with installing Home Assistant. The links below lead to Ameridroid. If youre not in the US, you should be able to find these items in web stores in your country.
To get started, we suggest the ODROID N2+, the board that powers our [Home Assistant Blue](/blue/), or the ODROID M1.
If unavailable, we also recommend the [ODROID C4](https://ameridroid.com/products/odroid-c4?ref=eeb6nfw07e).
Home Assistant bundles (US market):
The bundles come with Home Assistant pre-installed.
@ -25,7 +24,7 @@ The bundles come with Home Assistant pre-installed.
- [ODROID N2+: 4 GB RAM / 64 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44748729221399?ref=eeb6nfw07e)
- ODROID M1: 4 GB RAM / 256 GB NVMe / [16 GB &micro;SD](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44929573028119?ref=eeb6nfw07e) or [16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940567831?ref=eeb6nfw07e)
- ODROID M1: 8 GB RAM / 256 GB NVMe / [16 GB &micro;SD](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44929573093655?ref=eeb6nfw07e) or [16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940633367?ref=eeb6nfw07e)
- [ODROID M1: 8 GB RAM / 1 TB NVMe / 64 GB eMMC ](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940698903?ref=eeb6nfw07e)
- [ODROID M1: 8 GB RAM / 1 TB NVMe / 64 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940698903?ref=eeb6nfw07e)
Variants without pre-installed Home Assistant:
@ -47,14 +46,20 @@ Variants without pre-installed Home Assistant:
<div class='note'>
<b>Prerequisites</b>
This guide assumes that you have a dedicated {{ site.installation.types[page.installation_type].board }} PC (typically an Intel or AMD-based system) available to exclusively run Home Assistant Operating System. The system must be 64-bit capable and able to boot using UEFI. Pretty much all systems produced in the last 10 years support the UEFI boot mode.
This guide assumes that you have a dedicated {{ site.installation.types[page.installation_type].board }} PC to exclusively run the Home Assistant Operating System.
- This is typically an Intel or AMD-based system.
- The system must be 64-bit capable and be able to boot using UEFI.
- Most systems produced in the last 10 years support the UEFI boot mode.
<b>Summary</b>
You will need to configure your {{ site.installation.types[page.installation_type].board }} PC to use UEFI boot mode, then write the HAOS (Home Assistant OS) disk image to your boot medium. There are two ways to do this listed below.
1. First, you will need to configure your {{ site.installation.types[page.installation_type].board }} PC to use UEFI boot mode.
2. Then, write the Home Assistant Operating System disk image to your boot medium.
</div>
### Configure the BIOS on your x86-64 hardware
## Configure the BIOS on your x86-64 hardware
To boot Home Assistant OS, the BIOS needs to have UEFI boot mode enabled and Secure Boot disabled. The following screenshots are from a 7th generation Intel NUC system. The BIOS menu will likely look different on your system. However, the options should still be present and named similarly.
@ -71,46 +76,98 @@ To boot Home Assistant OS, the BIOS needs to have UEFI boot mode enabled and Sec
The BIOS configuration is now complete.
Next, we need to write the Home Assistant Operating System image to the "boot medium", which is the medium your x86-64 hardware will boot from when it is running Home Assistant.
## Write HAOS onto your x86-64 hardware
Next, you need to write the Home Assistant Operating System image to the *boot medium*, which is the medium your x86-64 hardware will boot from when it is running Home Assistant.
<div class='note'>
HAOS has no integrated installer that writes the image automatically, you must write it manually using e.g. Etcher.
HAOS has no integrated installer that writes the image automatically. You will write it manually using either the <b>Disks</b> utility from Ubuntu or Balena Etcher.
</div>
Typically an internal medium like S-ATA hard disk, S-ATA SSD, M.2 SSD, or a non-removable eMMC is used for the x86-64 boot medium. Alternatively, an external medium can be used such as a USB SDD, though this is not recommended.
Typically, an internal medium like S-ATA hard disk, S-ATA SSD, M.2 SSD, or a non-removable eMMC is used for the x86-64 boot medium. Alternatively, an external medium can be used such as a USB SDD, though this is not recommended.
To write the HAOS image to the boot medium on your x86-64 hardware, there are 2 different methods:
1. Write the HAOS disk image from your desktop computer directly to the boot medium (e.g. using a USB to S-ATA adapter).
If you can use this method, proceed to "[Write the image to your boot medium](#write-the-image-to-your-boot-medium)" and follow all steps. If you have non-removable internal mediums or don't have the necessary adapter, try the next method instead.
**Method 1 (recommended)**: Boot Ubuntu from a USB flash drive and install the Home Assistant Operating System from there. It also works on laptops and PCs with internal hard disks.
2. Create a "live operating system" on a USB device running e.g. Ubuntu ([how-to guide](https://ubuntu.com/tutorials/try-ubuntu-before-you-install)). Insert it into your system and boot the live operating system. Then follow from step 2 in "[Write the image to your boot medium](#write-the-image-to-your-boot-medium)".
**Method 2**: With this method, you write the Home Assistant Operating disk image directly onto a boot medium from your regular computer. The steps are a bit more complex. If you have non-removable internal mediums (for example because you are using a laptop) or do not have the necessary adapter (for example an USB to S-ATA adapter) use method 1 instead.
{% details "Ubuntu dependencies for Etcher" %}
### Method 1: Installing HAOS via Ubuntu booting from a USB flash drive
When installing Etcher on Ubuntu you may need to install the fuse dependency first,
to do this run the following commands in the terminal:
#### Required material
```bash
sudo add-apt-repository universe
sudo apt update
sudo apt install libfuse2
```
- Computer
- The target x86-64 hardware, on which you want to install the Home Assistant Operating System (HAOS)
- USB flash drive (USB thumb drive is sufficient, it should be at least 4&nbsp;GB in size)
- Internet connection
{% enddetails %}
#### To install HAOS via Ubuntu from a USB flash drive
{% endif %}
1. **Notice**: This procedure will write the Home Assistant Operating System onto your device.
- This means you will lose all the data as well as the previously installed operating system.
- Back up your data before carrying out this procedure.
2. Create a *live operating system* on a USB flash drive:
- Follow the [Ubuntu instructions](https://ubuntu.com/tutorials/try-ubuntu-before-you-install) on writing an Ubuntu iso file onto a USB device.
3. Insert the USB flash drive into the system on which you want to run Home Assistant.
- Boot the live operating system.
- You might need to adjust boot order or use F10 (might be a different F-key depending on the BIOS) to select the USB flash drive as boot device.
4. When prompted, make sure to select **Try Ubuntu**. This runs Ubuntu on the USB flash device.
- The system then starts Ubuntu.
- Connect your system to your network and make sure it has internet access.
5. In Ubuntu, open a browser and open [this procedure](/installation/generic-x86-64).
- From there, [download the image][generic-x86-64].
6. In Ubuntu, in the bottom left corner, select **Show Applications**.
7. In the applications, search and open **Disks** and start restoring the HOAS image:
1. In **Disks**, on the left side, select the internal disk device you want to install HAOS onto.
2. On top of the screen, select the three dots menu and select **Restore Disk Image...**.
![Restore disk image: select three dots menu](/images/installation/ubuntu_restore_disk_image.png)
3. Select the image you just downloaded.
![Restore disk image: select image](/images/installation/select_haos.png)
4. Select **Start Restoring...**.
![Restore disk image: start restoring](/images/installation/start_restoring.png)
5. Confirm by selecting **Restore**.
![Restore disk image: select Restore](/images/installation/restore.png)
- If you are getting an **Error unmounting filesystem** error message, stating that the **target is busy**:
- Most likely, you are running Ubuntu on your internal disk. Instead, you need to run it on your stick.
- Go back to step 3 and during start up, make sure you select **Try Ubuntu** (and NOT **Install Ubuntu**).
6. In the partitions overview, you should now see the restore operation in progress.
- The Home Assistant Operating System is now being installed on your system.
![Restore disk image: Restoring...](/images/installation/haos_restoring.png)
8. Once the Home Assistant Operating System is installed, shut down the system.
- Once Ubuntu has been shut down, remove the USB flash drive (Ubuntu will inform you when this is the case).
- Your Home Assistant server is now set up and you can start using it.
- To use it, proceed as described under [start up your generic x86-64](/installation/generic-x86-64#start-up-your-generic-x86-64).
### Method 2: Installing HAOS directly from a boot medium
Use this method only if Method 1 does not work for you.
#### Required material
- Computer
- The target x86-64 hardware, on which you want to install the Home Assistant Operating System (HAOS)
- Boot medium
- Internet connection
#### Write the image to your boot medium
{% else %}
### Write the image to your boot medium
1. Attach the Home Assistant boot medium ({{site.installation.types[page.installation_type].installation_media}}) to your computer.
{% if page.installation_type == 'odroid' %}
If you are using ODROID M1, note that booting from NVMe is not supported. If you want to boot from eMMC, [update the firmware](https://github.com/home-assistant/operating-system/blob/dev/Documentation/boards/hardkernel/odroid-m1.md) before installing the image.
If you are using a [Home Assistant Blue](/blue) or ODROID N2+, you can [attach your device directly](/common-tasks/os/#flashing-an-odroid-n2).
{% endif %}
2. Download and start <a href="https://www.balena.io/etcher" target="_blank">Balena Etcher</a>. You may need to run it with administrator privileges on Windows.
3. Download the image to your computer.
1. **Notice**: This procedure will write the Home Assistant Operating System onto your device.
- This means you will lose all the data as well as the previously installed operating system.
- Back up your data before continuing with the next step.
2. Attach the Home Assistant boot medium ({{site.installation.types[page.installation_type].installation_media}}) to your computer.
{% if page.installation_type == 'ODROID' %}
If you are using ODROID M1, note that booting from NVMe is not supported. If you want to boot from eMMC, [update the firmware](https://github.com/home-assistant/operating-system/blob/dev/Documentation/boards/hardkernel/odroid-m1.md) before installing the image.
If you are using a [Home Assistant Blue](/blue) or ODROID N2+, you can [attach your device directly](/common-tasks/os/#flashing-an-odroid-n2).
{% endif %}
3. Download and start <a href="https://www.balena.io/etcher" target="_blank">Balena Etcher</a>. You may need to run it with administrator privileges on Windows.
4. Download the image to your computer.
- Copy the URL for the image.
- If there are multiple links below, make sure to select the correct link for your version of {{site.installation.types[page.installation_type].board}}.
{% if site.installation.types[page.installation_type].variants.size > 1 %}
@ -127,7 +184,7 @@ sudo apt install libfuse2
{% if variant.key == "odroid-n2" %}
[Guide: Flashing Odroid-N2 using OTG-USB](/hassio/flashing_n2_otg/)
{% elsif variant.key == "rpi4" or variant.key == "rpi3" %}
_(64-bit is recommended)_
*(64-bit is recommended)*
{% endif %}
{% endfor %}
@ -141,30 +198,30 @@ sudo apt install libfuse2
{% endif %}
_Select and copy the URL or use the "copy" button that appear when you hover it._
*Select and copy the URL or use the "copy" button that appear when you hover it.*
4. Paste the URL into your browser to start the download.
5. Select **Flash from file** and select the image you just downloaded.
- **Flash from URL** does not work on some systems.
5. Paste the URL into your browser to start the download.
6. Select **Flash from file** and select the image you just downloaded.
- Do not use **Flash from URL**. It does not work on some systems.
![Screenshot of the Etcher software showing flash from URL selected.](/images/installation/etcher1_file.png)
6. **Select target**.
7. **Select target**.
![Screenshot of the Etcher software showing the select target button highlighted.](/images/installation/etcher3.png)
7. Select the boot medium ({{site.installation.types[page.installation_type].installation_media}}) you want to use for your installation.
![Screenshot of the Etcher software showing teh targets available.](/images/installation/etcher4.png)
8. Select **Flash!** to start writing the image.
8. Select the boot medium ({{site.installation.types[page.installation_type].installation_media}}) you want to use for your installation.
![Screenshot of the Etcher software showing the targets available.](/images/installation/etcher4.png)
9. Select **Flash!** to start writing the image.
- If the operation fails, decompress the .xz file and try again.
![Screenshot of the Etcher software showing the Flash button highlighted.](/images/installation/etcher5.png)
9. When Balena Etcher has finished writing the image, you will see a confirmation.
1. When Balena Etcher has finished writing the image, you will see a confirmation.
![Screenshot of the Etcher software showing that the installation has completed.](/images/installation/etcher6.png)
### Start up your {{site.installation.types[page.installation_type].board}}
{% if page.installation_type == 'generic-x86-64' %}
- If you used your desktop system to write the HAOS image directly to a boot medium like an S-ATA SSD, connect this back to your {{ site.installation.types[page.installation_type].board }} system.
- If you used method 1 for the installation, make sure the USB flash drive is removed from the system.
- If you used a live operating system (e.g. Ubuntu), shut it down and remove the live operating system USB device.
- If you used method 2 for the installation, install the boot medium into your x86-64 hardware.
1. Plug in an Ethernet cable that is connected to the network.
2. Power the system on. If you have a screen connected to the {{site.installation.types[page.installation_type].board}} system, after a minute or so the Home Assistant welcome banner will appear in the console.
@ -208,7 +265,7 @@ If you are running an older Windows version or have a stricter network configura
### Download the appropriate image
- [VirtualBox][vdi] (.vdi)
{% if page.installation_type == 'windows' or page.installation_type == 'linux' %}
{% if page.installation_type == 'windows' or page.installation_type == 'Linux' %}
- [KVM][qcow2] (.qcow2)
- [Vmware Workstation][vmdk] (.vmdk)
{% elsif page.installation_type == 'alternative' %}
@ -221,10 +278,11 @@ If you are running an older Windows version or have a stricter network configura
After downloading, decompress the image. If the image comes in a ZIP file, for example, unzip it.
Follow this guide if you already are running a supported virtual machine hypervisor. If you are not familiar with virtual machines, we recommend installing Home Assistant OS directly on a [Home Assistant Yellow](/installation/yellow), a [Raspberry Pi](/installation/raspberrypi), or an [ODROID](/installation/odroid).
Follow this guide if you already are running a supported virtual machine hypervisor. If you are not familiar with virtual machines, install Home Assistant OS directly on a [Home Assistant Yellow](/installation/yellow), a [Raspberry Pi](/installation/raspberrypi), or an [ODROID](/installation/odroid).
{% if page.installation_type == 'macos' %}
- If VirtualBox is not supported on your Mac, and you have experience using virtual machines, you can try running the Home Assistant Operating system on [UTM](https://mac.getutm.app/).
{% if page.installation_type == 'macOS' %}
- If VirtualBox is not supported on your Mac, and you have experience using virtual machines, you can try running the Home Assistant Operating System on [UTM](https://mac.getutm.app/).
{% endif %}
### Create the virtual machine
@ -237,7 +295,7 @@ Minimum recommended assignments:
- 32 GB Storage
- 2vCPU
_All these can be extended if your usage calls for more resources._
*All these can be extended if your usage calls for more resources.*
### Hypervisor specific configuration
@ -259,9 +317,11 @@ _All these can be extended if your usage calls for more resources._
By default, VirtualBox does not free up unused disk space. To automatically shrink the vdi disk image
the `discard` option must be enabled using your host machine's terminal:
```bash
VBoxManage storageattach <VM name> --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on
```
More details can be found about the command can be found [here](https://www.virtualbox.org/manual/ch08.html#vboxmanage-storageattach).
</div>
@ -273,7 +333,7 @@ _All these can be extended if your usage calls for more resources._
3. Make sure under **Settings** > **VM manager**, **Enable VMs** is enabled.
4. Create a new virtual machine: **VMS** > **Add VM**.
5. Select type **Linux** and give the VM a name and a description.
6. Select the CPU cores you want to let the VM use and give it some memory.
6. Select the CPU cores you want to let the VM use and give it some memory.
7. Under **Primary vDisk Location**, select **Manual** and then select the qcow2 image.
8. Select your keyboard language under **VM Console Keyboard**.
9. Select **br0** under **Network Source**.
@ -284,8 +344,8 @@ _All these can be extended if your usage calls for more resources._
14. Select the name of your new VM and select the capacity number for your disk. Here, you can expand the disk to whatever your needs are. The default is 32&nbsp;GB.
15. Select the icon of your new VM and select **start with console (VNC)**.
{% unless page.installation_type == 'macOS' %}
{% unless page.installation_type == 'macos' %}
- title: KVM (virt-manager)
content: |
1. Create a new virtual machine in `virt-manager`.
@ -301,9 +361,11 @@ _All these can be extended if your usage calls for more resources._
- title: KVM (virt-install)
content: |
```bash
virt-install --name hass --description "Home Assistant OS" --os-variant=generic --ram=2048 --vcpus=2 --disk <PATH TO QCOW2 FILE>,bus=sata --import --graphics none --boot uefi
```
<div class="note info">
If you have a USB dongle to attach, you need to add the option `--hostdev busID.deviceId`. You can discover these IDs via the `lsusb` command.
As example, if `lsusb` output is:
@ -324,12 +386,14 @@ _All these can be extended if your usage calls for more resources._
```bash
virt-install --name hass --description "Home Assistant OS" --os-variant=generic --ram=2048 --vcpus=2 --disk <PATH TO QCOW2 FILE>,bus=sata --import --graphics none --boot uefi --hostdev 003.003
```
Note that this configuration (bus 003, device 003) is just an example, your dongle could be on another bus and/or with another device ID.
Note that this configuration (bus 003, device 003) is just an example, your dongle could be on another bus and/or with another device ID.
Please check the correct IDs of your USB dongle with `lsusb`.
</div>
{% endunless %}
{% if page.installation_type == 'windows' or page.installation_type == 'linux' %}
{% if page.installation_type == 'windows' or page.installation_type == 'Linux' %}
- title: Vmware Workstation
content: |

Binary file not shown.

After

Width:  |  Height:  |  Size: 95 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 88 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 33 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 102 KiB