Skip to content

Instantly share code, notes, and snippets.

@coltenkrauter

coltenkrauter/detailed-home-assistant-os-installation-in-vm-on-truenas-scale.md

Last active December 10, 2024 11:14
Show Gist options
  • Save coltenkrauter/aee059954b11bf4f6461309af521a277 to your computer and use it in GitHub Desktop.
Save coltenkrauter/aee059954b11bf4f6461309af521a277 to your computer and use it in GitHub Desktop.
Download ZIP
Comprehensive instructions for installing Home Assistant OS in a VM on TrueNAS SCALE.
Raw
detailed-home-assistant-os-installation-in-vm-on-truenas-scale.md

Installing Home Assistant OS in a VM on TrueNAS SCALE

This guide provides detailed steps to install Home Assistant OS (HAOS) in a Virtual Machine (VM) on TrueNAS SCALE.

Table of Contents

Why Install Home Assistant OS on a VM?

Installing Home Assistant OS on a VM gives you the full package of features, including the Supervisor and Add-ons. Here's why this setup rocks:

  1. Add-Ons: You get access to Home Assistant Add-ons, which are like plugins that expand your setup with extra functionalities—think MQTT brokers, databases, or Node-RED.
  2. Supervisor: The Supervisor manages your Home Assistant instance, making updates, backups, and system health checks a breeze.
  3. Snapshots: VMs make it easy to snapshot your entire setup. Mess something up? Rollback to a previous state in no time.
  4. Isolation: Your Home Assistant OS runs in its own VM, separate from other systems, reducing the risk of conflicts.
  5. Resource Management: Allocate exactly the resources you need, ensuring Home Assistant runs smoothly without hogging everything else.

For more details, you can check out the Home Assistant OS Installation Guide and the TrueNAS Community Forum.

Requirements

  1. TrueNAS SCALE installed.
  2. TrueNAS SCALE shell access.

This guide was tested against:

  • Version: TrueNAS-SCALE-23.10.2
  • Product: TRUENAS-MINI-3.0-X+
  • Model: Intel(R) Atom(TM) CPU C3758 @ 2.20GHz
  • Memory: 31 GiB

Create a ZVOL

Note: A ZVOL is used instead of a dataset because it allows the storage to be presented as a block device, which is necessary for VM disk images to function correctly.

  1. Open TrueNAS SCALE web interface.
  2. Navigate to Storage > Pools.
  3. Select your pool and click Add Zvol.
  4. Set the following:
    • Name: HomeAssistantOS
    • Size: At least 32 GiB
    • Sync: STANDARD
    • Compression Level: Inherit (LZ4)
    • Enable Atime: ON
    • ZFS Deduplication: OFF
    • Case Sensitivity: ON
    • Comments: Home Assistant OS
  5. Note the ZVOL path, which will be something like /mnt/your-pool-name/HomeAssistantOS.

Setup VM in TrueNAS SCALE

  1. Open TrueNAS SCALE web interface.
    • Navigate to Virtualization > VMs.
    • Click Add to create a new VM.
  2. Configure VM settings:
    • Guest Operating System: Linux
    • Name: HAOS
    • Description: Home Assistant OS
    • System Clock: UTC
    • Boot Method: UEFI
    • Shutdown Timeout: 90
    • Start on Boot: Enabled
    • Enable Display: Enabled
    • Bind: 0.0.0.0
    • Password: Set a password for VNC access
  3. CPU and Memory:
    • Virtual CPUs: At least 2 vCPUs
    • Cores: 2
    • Threads: 1
    • CPU Mode: Host Passthrough
    • Memory Size: At least 4096 MB
  4. Add Storage:
    • Select Disk Type: VIRTIO
    • Use existing disk image: Attach the ZVOL created earlier
  5. Configure Network:
    • Adapter Type: VirtIO
    • Mac Address: Auto-generated
    • Attach NIC: Select the network interface used by your system
    • Choose a NIC for your VM. Set the adapter type to VirtIO. If you are not using a bridge, enable Trust Guest Filters to allow multicast.
  6. GPU:
    • Hide from MSR: Disabled
    • Ensure Display Device: Enabled
  7. Confirm Options and save the VM configuration.

Install HAOS

Note: Here we are just downloading an image and writing it to the disk. The disk in our case is the ZVOL. These steps would be considered the installation. After that, it’s just a matter of adding the ZVOL to a VM and booting up.

  1. Download the latest HAOS image using TrueNAS SCALE shell:

    Note that these commands may require admin privilages and per TrueNAS documentation,

    Restrict new TrueNAS user accounts (CORE | SCALE) to the most minimal set of storage ACL permissions and access possible.

    On TrueNAS SCALE, create the administrator account on install and disable root NAS administrative access...

    wget https://github.com/home-assistant/operating-system/releases/download/12.3/haos_ova-12.3.qcow2.xz
unxz haos_ova-12.3.qcow2.xz
sudo qemu-img convert -O raw haos_ova-12.3.qcow2 /dev/zvol/<path_to_zvol>

  2. Start the VM.

    • The system should boot directly from the ZVOL and load Home Assistant OS.

Post-Installation

  1. Access the HAOS web interface:
    • Open a web browser and navigate to http://<vm-ip>:8123.
  2. Complete the initial Home Assistant setup:
    • Set up user account.
    • Configure basic settings.
  3. Verify the installation by checking the system information and logs.

Troubleshooting

qemu-img: /dev/zvol/<path_to_zvol>: error while converting raw: Cannot grow device files

This error occurs when trying to convert the HAOS image to a ZVOL and the ZVOL does not have sufficient space or is incorrectly configured.

Solution:

  1. Ensure the ZVOL has enough space.
  2. Check the ZVOL path and permissions.
  3. Recreate the ZVOL if necessary, ensuring it is at least 32 GiB in size.

VM Stuck in GRUB Loop

If your VM stays in an eternal loop in GRUB, it may indicate a problem with the installation or the image file.

Solution:

  1. Ensure the image file is not corrupted.
  2. Re-download and extract the image file.
  3. Check the ZVOL path and permissions.

USB Passthrough Issues

Issues with USB passthrough can often be resolved by ensuring the correct device path and settings.

Solution:

  1. Ensure the USB device is correctly identified and passed through.
  2. Use PCIe passthrough for the USB controller rather than USB passthrough per device to avoid issues​:citation[oaicite:2]{index=2}​​:citation[oaicite:1]{index=1}​.

Home Assistant CLI Not Starting

If the Home Assistant CLI is not starting, it may be due to a corrupted download or incorrect setup.

Solution:

  1. Delete any existing HAOS files.
  2. Re-download and extract the HAOS image.
  3. Ensure the ZVOL is correctly configured and has enough space​:citation[oaicite:0]{index=0}​.

Resources

Collaboration

For contributions, open an issue or pull request in the repository.

Credits

Content based on the Home Assistant Community Guide, Home Assistant OS Installation Guide, and TrueNAS Community Forum.

Authored with assistance from GPT-4, provided by OpenAI.

@ruifaguiar
Copy link

ruifaguiar commented Oct 14, 2024 •
edited
Loading

First of all, thank you for your guide. Appreciate your share.

qemu-img convert -O raw haos_ova-12.3.qcow2 /dev/zvol/<path_to_zvol>
this command should be run with a user with elevated priviledges. Truenas installation now sugests that we use a admin account instead of root. With this account we need to add sudo to the command

@coltenkrauter
Copy link
Author

Thanks for the input @ruifaguiar–I added the following to the above guide based on your feedback.

Note that these commands may require admin privilages and per TrueNAS documentation,

> Restrict new TrueNAS user accounts (CORE | SCALE) to the most minimal set of storage ACL permissions and access possible.
> > 
> On TrueNAS SCALE, create the administrator account on install and disable root NAS administrative access...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment