How to Run Home Assistant on Docker

This article contains affiliate links. If you purchase through our links, we may earn a commission at no extra cost to you. We only recommend products we’ve thoroughly researched and verified.

Running Home Assistant alongside other services on a single mini PC requires choosing how HA integrates with your existing setup. This guide covers three approaches — HAOS bare metal, Home Assistant Supervised on Ubuntu, and HAOS in Proxmox VM — so you can pick the right method for your hardware and goals.

Recommended hardware:

• Beelink MINI S12 dedicated HAOS host — See current alternatives
• Beelink EQ14 HA + Docker homelab — See current alternatives

---

Choosing Your Installation Method

---

Method 1: HAOS Bare Metal Recommended for Most

Best for: Dedicated Home Assistant hosts, users who want the simplest setup.

Step 1: Download and Flash HAOS

1. Go to home-assistant.io/installation/generic-x86-64
2. Download the latest haos_generic-x86-64-X.X.img.xz
3. Flash to a USB drive with Balena Etcher

Step 2: Install to Mini PC

1. Boot mini PC from the USB drive press F7, F11, or Del during boot for boot menu
2. HAOS automatically installs to the NVMe drive — takes 3-5 minutes
3. Remove USB drive when installation completes, reboot

Step 3: Initial Setup

Access Home Assistant at http://homeassistant.local:8123 from any device on your network. If hostname resolution fails: find the mini PC’s IP in your router’s connected devices list and use that directly.

Create your account and Home Assistant begins onboarding.

Connecting USB Devices Zigbee/Z-Wave

HAOS automatically detects USB serial devices. Plug in your Zigbee coordinator or Z-Wave stick. In HA:

1. Settings → Hardware → USB Devices — verify your coordinator appears
2. Install Zigbee2MQTT or ZHA add-on
3. Select the detected USB device as coordinator

---

Method 2: Home Assistant Supervised on Ubuntu

Best for: Users who want HAOS add-on support alongside other Docker services on the same Ubuntu installation.

Step 1: Install Ubuntu Server 24.04 LTS

Install Ubuntu Server 24.04 with SSH enabled. Set a static IP.

Step 2: Install Dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  apparmor \
  cifs-utils \
  curl \
  dbus \
  jq \
  libglib2.0-bin \
  lsb-release \
  network-manager \
  nfs-common \
  systemd-journal-remote \
  systemd-resolved \
  udisks2 \
  wget

Step 3: Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Step 4: Install OS Agent

# Get latest version from GitHub releases
AGENT_VERSION=$(curl -s https://api.github.com/repos/home-assistant/os-agent/releases/latest | jq -r .tag_name)
wget "https://github.com/home-assistant/os-agent/releases/download/${AGENT_VERSION}/os-agent_${AGENT_VERSION}_linux_x86_64.deb"
sudo dpkg -i os-agent_${AGENT_VERSION}_linux_x86_64.deb

# Verify
sudo gdbus introspect --system --dest io.hass.os --object-path /io/hass/os

Step 5: Install Home Assistant Supervised

# Download installer
wget https://github.com/home-assistant/supervised-installer/releases/latest/download/homeassistant-supervised.deb

# Install
sudo dpkg -i homeassistant-supervised.deb

# Select machine type: generic-x86-64

Wait 10-15 minutes for the initial HAOS container stack to pull and start. Access at http://<server-ip>:8123.

Verify Supervised Installation

# Check all HAOS containers are running
docker ps | grep hassio

Expected containers: hassio_supervisor, hassio_homeassistant, hassio_dns, hassio_audio, hassio_multicast, hassio_observer

---

Method 3: HAOS in Proxmox VM Best for Homelabs

Best for: Running HAOS in full isolation alongside Docker services, other VMs, and Proxmox management.

Step 1: Install Proxmox

Flash Proxmox VE 8.x ISO to USB and install on the mini PC.

# After install, disable enterprise repo and enable community:
sed -i 's/^deb/#deb/' /etc/apt/sources.list.d/pve-enterprise.list
echo 'deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription' \
  >> /etc/apt/sources.list
apt update && apt dist-upgrade

Step 2: Create HAOS VM

Use the community HAOS Proxmox installer script widely used, saves manual configuration:

# Run on Proxmox host
bash -c "$(curl -fsSL https://raw.githubusercontent.com/tteck/Proxmox/main/vm/haos-vm.sh)"

The script:

• Downloads the latest HAOS x86_64 image
• Creates a VM with appropriate settings machine type: q35, BIOS: OVMF UEFI
• Imports the disk image
• Configures networking

Or create manually:

# Download HAOS image
wget https://github.com/home-assistant/operating-system/releases/download/12.x/haos_generic-x86-64-12.x.img.xz
xz -d haos_generic-x86-64-12.x.img.xz

# Create VM in Proxmox
qm create 100 \
  --name homeassistant \
  --memory 4096 \
  --cores 2 \
  --net0 virtio,bridge=vmbr0 \
  --bios ovmf \
  --machine q35 \
  --efidisk0 local-lvm:0,format=raw

# Import HAOS disk
qm importdisk 100 haos_generic-x86-64-12.x.img local-lvm

# Attach the imported disk
qm set 100 --scsi0 local-lvm:vm-100-disk-1 --boot c --bootdisk scsi0

# Start VM
qm start 100

Step 3: USB Passthrough for Zigbee/Z-Wave

In Proxmox → VM 100 → Hardware → Add → USB Device:

1. Select “Use USB Vendor/Device ID”
2. Find your Zigbee coordinator in the list e.g., “Silicon Labs Zigbee USB Dongle”
3. Add — the USB device now passes directly to the HAOS VM

Verify in HAOS: Settings → Hardware → USB Devices shows the coordinator.

---

Configuring Zigbee2MQTT in HAOS

After HAOS is running any method, install and configure Zigbee2MQTT:

1. Settings → Add-ons → Add-on Store → search “Zigbee2MQTT”
2. Install → Start
3. Configuration tab:

# Zigbee2MQTT configuration
serial:
  port: /dev/ttyUSB0   # Or use by-id path
  adapter: zstack      # For CC2652P (Sonoff Zigbee 3.0)

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://core-mosquitto:1883
  user: homeassistant
  password: your_mqtt_password

homeassistant: true

frontend:
  port: 8099

Save and restart the add-on. Zigbee2MQTT discovers your devices automatically.

---

Optimizing Home Assistant Performance

Move Database to NVMe

By default HAOS stores the SQLite database on the same drive. For mini PCs with fast NVMe, this is already optimal. But if you’re writing to an external drive or network share, move the data directory:

Settings → System → Storage → Move data to a different location

Enable Long-Term Statistics

# configuration.yaml
recorder:
  purge_keep_days: 30      # Keep 30 days of history
  db_url: sqlite:////config/home-assistant_v2.db

  include:
    domains:
      - sensor
      - binary_sensor
      - climate
    entity_globs:
      - sensor.temperature_*
      - sensor.humidity_*

Add-on Resource Limits

For resource-intensive add-ons, set memory limits:

In add-on settings → Network tab → Resource limits — typically not needed on EQ14 or MINI S12 but helps prevent memory runaway on 8GB systems.

---

Troubleshooting

Zigbee Dongle Not Detected

# On host (Ubuntu or Proxmox)
dmesg | grep -i tty
ls /dev/serial/by-id/

The by-id path is stable across reboots — use it in Zigbee2MQTT config instead of /dev/ttyUSBX.

HAOS Can’t Find HomeAssistant.local

mDNS isn’t always reliable across VLANs or certain routers. Use the IP address directly:

# Find HAOS IP from Proxmox:
qm guest exec 100 -- ip addr show eth0

Home Assistant Updates Break Supervised Install

With HA Supervised: keep Debian/Ubuntu updated but be cautious with major OS version upgrades — they can break the Supervised install. HAOS bare metal and Proxmox VM methods don’t have this risk.

---

Who Should Skip This Comparison

Frequently Asked Questions

Should I use ZHA or Zigbee2MQTT with Home Assistant?

ZHA is built into HA and simpler — works out of the box with most coordinators. Zigbee2MQTT is an add-on with broader device support more device definitions maintained by the community and exposes raw MQTT for automation. Start with ZHA; switch to Z2M if you encounter unsupported devices.

Can I run Home Assistant and Plex on the same mini PC?

Yes on EQ14 with 16GB. Method: Proxmox with HAOS VM 2 cores, 4GB + Plex LXC 2 cores, 4GB + remaining resources for other containers. Or: Ubuntu with HA Supervised + Plex Docker container alongside. Either approach works within the EQ14’s 16GB RAM.

How do I back up Home Assistant?

In HAOS: Settings → Backups → Create backup. Store backups off the mini PC — use the Backup add-on to automatically upload to Google Drive, Dropbox, or a local NAS. The default local backup is vulnerable to the same storage failure that could corrupt HA itself.

What happens when HA needs an update and other services are on the same machine?

HAOS updates restart the HA container but don’t affect other Docker containers running on the same host. Proxmox VM updates are fully isolated — updating HAOS restarts the VM but not adjacent VMs or LXC containers.

Is Home Assistant Supervised still officially supported?

Yes, but with caveats. Home Assistant Supervised is officially supported only on Debian not Ubuntu running on bare metal. Ubuntu is not on the official supported OS list, though it works in practice. For a fully supported configuration: use HAOS bare metal or HAOS in Proxmox VM. For maximum flexibility: HA Supervised on Ubuntu works but may encounter issues with major OS changes.

What is the difference between HAOS, Home Assistant Supervised, and Home Assistant Container?

HAOS is a full operating system image — install it directly on the mini PC from USB for the simplest setup with full add-on support. Home Assistant Supervised runs on top of your existing Linux OS Ubuntu, Debian via Docker and provides the same add-on functionality as HAOS. Home Assistant Container is a plain Docker image that runs just the HA core — no add-on support, not recommended for most users.