The Ultimate Guide to Installing and Securing Home Assistant on Ubuntu 20.04+

Home Assistant is a powerful open-source home automation platform that puts local control and privacy first. It allows you to integrate and control all your smart devices from a single dashboard, creating automations that make your home truly smart. This comprehensive guide will walk you through installing Home Assistant on Ubuntu 20.04 and newer versions using multiple methods, ensuring you select the one that best fits your needs and technical comfort level.

Introduction: Understanding Your Installation Options#

Before diving into installation procedures, it's crucial to understand that Home Assistant offers several installation methods, each with different features and complexity levels. We'll cover Docker installation (most flexible), VM installation (most isolated), and direct OS installation (most integrated).

Home Assistant comes in several flavors, each with its own benefits and trade-offs:

1. Home Assistant OS: A complete, managed operating system designed specifically for Home Assistant. This is the recommended method for dedicated devices.
2. Home Assistant Container: Running Home Assistant in a Docker container. Great for users who want to run Home Assistant alongside other services on the same machine.
3. Home Assistant Supervised: A middle ground that allows you to install the Supervisor component on top of a regular operating system.
4. Home Assistant Core: The most minimal installation, without the Supervisor and add-ons.

This table compares key features across installation methods:

*Home Assistant Supervised requires users to maintain their own operating system.

Method 1: Installing Home Assistant Using Docker (Recommended)#

Docker provides an excellent balance of flexibility and isolation, making it ideal for running Home Assistant on an existing Ubuntu system. This method is perfect if you're already running other services on your machine and want to keep Home Assistant contained.

Prerequisites#

• Ubuntu 20.04 or newer installed and updated
• A user with sudo privileges
• Minimum hardware: 2GB RAM, dual-core CPU, 32GB storage
• Network: Port 8123 (Home Assistant web interface) should be accessible
• Basic familiarity with terminal commands

Step 1: Update Your Ubuntu System#

First, ensure your system is fully updated to prevent any dependency issues:

sudo apt update && sudo apt upgrade -y

This updates your package list and upgrades all installed packages to their latest versions. If the update fails, check your internet connection or try changing your APT mirror.

Step 2: Install Required Dependencies#

Install the necessary packages for Docker installation:

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common gnupg lsb-release

These packages enable secure APT connections and provide tools needed for the Docker repository. If you encounter any "package not found" errors, your APT sources may be incomplete.

Step 3: Add Docker's Official GPG Key#

Add Docker's official GPG key to ensure package authenticity:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

This command downloads Docker's GPG key and adds it to your system. If it fails, check your internet connection or try again later.

Step 4: Set Up the Docker Repository#

Add the Docker repository to your APT sources:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

This command adds the appropriate Docker repository for your Ubuntu version. If you see an error about an unsupported distribution, you may need to manually specify a supported Ubuntu codename.

Step 5: Install Docker Engine#

Update the package index and install Docker:

sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

This installs the Docker Engine, CLI, containerd runtime, and Docker Compose plugin. If the installation fails, check the Docker compatibility with your specific Ubuntu version.

Step 6: Add Your User to the Docker Group#

Add your user to the Docker group to run Docker commands without sudo:

sudo usermod -aG docker $USER

This command adds your current user to the Docker group. For the changes to take effect, you'll need to log out and log back in, or run newgrp docker to update your current session.

Step 7: Create a Directory for Home Assistant Configuration#

Create a directory to store your Home Assistant configuration files:

mkdir -p ~/homeassistant/config

This creates a directory structure for Home Assistant's persistent data. If the command fails, check that you have write permissions to your home directory.

Step 8: Run Home Assistant Container#

Now, run the Home Assistant container with the configuration volume mounted:

docker run -d \
  --name=homeassistant \
  --restart=unless-stopped \
  --network=host \
  -v ~/homeassistant/config:/config \
  -v /etc/localtime:/etc/localtime:ro \
  --privileged \
  ghcr.io/home-assistant/home-assistant:stable

This command starts Home Assistant in a Docker container with access to your network and mounts the configuration directory. The --privileged flag is needed for certain integrations, though it has security implications. If the container doesn't start, check the Docker logs with docker logs homeassistant.

Step 9: Verify Home Assistant is Running#

Check that Home Assistant started successfully:

docker ps | grep homeassistant

You should see the running container in the output. If not, check the logs for errors: docker logs homeassistant.

Step 10: Access Home Assistant Web Interface#

Open a web browser and navigate to:

http://YOUR_SERVER_IP:8123

Replace YOUR_SERVER_IP with your server's IP address. The initial setup will take a few minutes as Home Assistant downloads and initializes components. If you can't access the web interface, ensure port 8123 isn't blocked by a firewall.

Method 2: Installing Home Assistant OS in a Virtual Machine#

If you prefer a more isolated installation or want the complete Home Assistant experience with add-ons, installing Home Assistant OS in a virtual machine is an excellent option.

Prerequisites#

• Ubuntu 20.04 or newer as host OS
• At least 4GB of free RAM and 2 CPU cores
• 32GB of free disk space
• Virtualization enabled in BIOS/UEFI
• Administrator privileges

Step 1: Install KVM and Required Packages#

Install KVM and related packages for virtualization:

sudo apt update && sudo apt install -y qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virt-manager ovmf

These packages provide the necessary components for KVM virtualization. If the installation fails, ensure your CPU supports virtualization and that it's enabled in your BIOS/UEFI settings.

Step 2: Add Your User to Virtualization Groups#

Add your user to the libvirt and kvm groups:

sudo adduser $USER libvirt
sudo adduser $USER kvm

This grants your user permission to manage virtual machines. Log out and back in for these changes to take effect.

Step 3: Verify Libvirt is Running#

Check that the libvirt daemon is running:

sudo systemctl status libvirtd

If it's not running, start and enable it:

sudo systemctl enable --now libvirtd

Step 4: Download Home Assistant OS Image#

Create a directory for the VM image and download the latest Home Assistant OS:

mkdir -p ~/hassos-vm && cd ~/hassos-vm
wget https://github.com/home-assistant/operating-system/releases/download/10.0/haos_ova-10.0.qcow2.xz

This downloads the latest QCOW2 image for Home Assistant OS. If the link is outdated, visit the Home Assistant GitHub releases page for the current version.

Step 5: Extract the Image#

Extract the downloaded image:

unxz haos_ova-10.0.qcow2.xz

This extracts the compressed QCOW2 image. If the command fails, ensure you have the xz-utils package installed.

Step 6: Create a Virtual Machine#

Create a virtual machine using the extracted image:

sudo virt-install \
  --name homeassistant \
  --memory 4096 \
  --vcpus 2 \
  --import \
  --disk ~/hassos-vm/haos_ova-10.0.qcow2,format=qcow2 \
  --os-variant generic \
  --network bridge=virbr0 \
  --graphics none \
  --boot uefi

This creates a VM with 4GB RAM and 2 vCPUs. If you encounter errors about missing firmware, ensure the ovmf package is properly installed. Adjust the memory and CPU values based on your system capabilities.

Step 7: Find Your VM's IP Address#

List your virtual machines and find their IP addresses:

sudo virsh list
sudo virsh domifaddr homeassistant

Note the IP address from the output. If no IP address is displayed, wait a few minutes for the VM to fully boot and obtain an IP address.

Step 8: Access Home Assistant#

Open a web browser and navigate to:

http://VM_IP_ADDRESS:8123

Replace VM_IP_ADDRESS with the IP address obtained in the previous step. The initial setup will take a few minutes. If you can't access the web interface, ensure the VM is running and has network connectivity.

Step 9: Enable Automatic Start for the VM#

Configure the VM to start automatically when your system boots:

sudo virsh autostart homeassistant

This ensures Home Assistant will be available after system reboots. If the command fails, check that the VM exists and that you have sufficient privileges.

Method 3: Installing Home Assistant Core on Ubuntu#

For users who want to run Home Assistant directly on their Ubuntu system without containerization or virtualization, Home Assistant Core is a viable option, though it lacks the add-on system available in other methods.

Prerequisites#

• Ubuntu 20.04 or newer
• Python 3.11 or newer
• 2GB RAM minimum (4GB recommended)
• 32GB storage space
• Administrator privileges

Step 1: Install Required Dependencies#

Install the necessary packages for Home Assistant Core:

sudo apt update && sudo apt install -y python3-pip python3-dev python3-venv libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libtiff5 libturbojpeg0-dev tzdata ffmpeg liblapack3 liblapack-dev libatlas-base-dev

These packages provide essential libraries for Home Assistant. If any package installation fails, try running sudo apt update again or check for specific package name changes in your Ubuntu version.

Step 2: Install Python 3.11#

Add the deadsnakes PPA and install Python 3.11:

sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update
sudo apt install -y python3.11 python3.11-dev python3.11-venv

This installs Python 3.11 and related development packages. If you're using Ubuntu 22.04 or newer, Python 3.10+ might already be installed, but 3.11 is recommended for best compatibility with Home Assistant.

Step 3: Create a Home Assistant User#

Create a dedicated user for running Home Assistant:

sudo useradd -rm homeassistant
sudo usermod -aG dialout homeassistant

This creates a system user and adds it to the dialout group for serial device access. If the user already exists, you can skip this step.

Step 4: Create the Home Assistant Directory#

Create a directory for Home Assistant and set the proper ownership:

sudo mkdir -p /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant

This creates the directory where Home Assistant will be installed and gives ownership to the homeassistant user. If the directory already exists, adjust the commands accordingly.

Step 5: Create and Activate Virtual Environment#

Switch to the homeassistant user and create a Python virtual environment:

sudo -u homeassistant -H -s
cd /srv/homeassistant
python3.11 -m venv .
source bin/activate

This creates an isolated Python environment for Home Assistant. If you encounter an error about Python 3.11 not being found, ensure it was installed correctly in step 2.

Step 6: Install Home Assistant Core#

With the virtual environment activated, install Home Assistant:

pip3 install wheel
pip3 install homeassistant

This installs the wheel package (required for some dependencies) and then Home Assistant itself. The installation may take several minutes. If you encounter errors about missing C compilers, ensure the build-essential package is installed.

Step 7: Start Home Assistant for the First Time#

Launch Home Assistant to complete the initial setup:

hass

This starts Home Assistant and initializes the configuration directory. Wait until you see "Home Assistant is now available at http://localhost:8123" in the console output. The first startup may take 5-10 minutes as dependencies are downloaded and compiled.

Press Ctrl+C to stop Home Assistant after the initial setup is complete.

Step 8: Create a Systemd Service#

Exit the homeassistant user shell:

exit

Create a systemd service file for Home Assistant:

sudo nano /etc/systemd/system/[email protected]

Add the following content to the file:

[Unit]
Description=Home Assistant
After=network-online.target

[Service]
Type=simple
User=%i
WorkingDirectory=/srv/homeassistant
ExecStart=/srv/homeassistant/bin/hass -c "/srv/homeassistant/.homeassistant"
Restart=on-failure
RestartForceExitStatus=100

[Install]
WantedBy=multi-user.target

This creates a systemd service to manage Home Assistant. If you've installed Home Assistant in a different location, adjust the paths accordingly.

Step 9: Enable and Start the Home Assistant Service#

Enable the service to start on boot and start it immediately:

sudo systemctl enable [email protected]
sudo systemctl start [email protected]

This enables and starts the Home Assistant service. Check its status with:

sudo systemctl status [email protected]

If the service fails to start, check the logs for errors:

sudo journalctl -fu [email protected]

Step 10: Access Home Assistant#

Open a web browser and navigate to:

http://YOUR_SERVER_IP:8123

Replace YOUR_SERVER_IP with your server's IP address. Complete the initial setup by creating an admin account. If you can't access the web interface, check that port 8123 isn't blocked by a firewall.

Securing Your Home Assistant Installation#

Regardless of which installation method you choose, securing your Home Assistant instance is crucial, especially if you plan to access it remotely.

Set Up HTTPS with Let's Encrypt#

If you're using Docker, you can add a reverse proxy like Nginx Proxy Manager or Traefik alongside Home Assistant:

Option 1: Using Nginx Proxy Manager#

Create a docker-compose.yml file that includes both Home Assistant and Nginx Proxy Manager:

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ~/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    network_mode: host
    
  nginx-proxy-manager:
    container_name: nginx-proxy-manager
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ~/nginx-proxy-manager/data:/data
      - ~/nginx-proxy-manager/letsencrypt:/etc/letsencrypt

Start the services:

docker compose up -d

Access Nginx Proxy Manager at http://YOUR_SERVER_IP:81 and set up a proxy host for your Home Assistant instance, enabling SSL with Let's Encrypt.

Restrict Access with Strong Authentication#

• Use a strong, unique password for your Home Assistant admin account
• Enable Two-Factor Authentication in Home Assistant
• Consider using a separate user account for day-to-day usage

Configure a Firewall#

Install and configure UFW (Uncomplicated Firewall):

sudo apt install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 8123/tcp  # Only if you need direct access to Home Assistant
sudo ufw enable

Verify the firewall status:

sudo ufw status

If you're using a reverse proxy, you only need to allow ports 80 and 443 instead of 8123.

Data Persistence and Backup Procedures#

Protecting your Home Assistant configuration and data is essential for disaster recovery.

Creating Regular Backups#

For Docker Installations#

Install the Auto Backup add-on in Home Assistant (if using Supervisor) or create a script for automated backups:

mkdir -p ~/homeassistant/backups

Create a backup script:

nano ~/backup-homeassistant.sh

Add the following content:

#!/bin/bash
TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
BACKUP_DIR=~/homeassistant/backups
mkdir -p $BACKUP_DIR
tar -czf $BACKUP_DIR/homeassistant-config-$TIMESTAMP.tar.gz -C ~/homeassistant config
echo "Backup created: $BACKUP_DIR/homeassistant-config-$TIMESTAMP.tar.gz"

Make the script executable:

chmod +x ~/backup-homeassistant.sh

Set up a cron job to run backups weekly:

(crontab -l 2>/dev/null; echo "0 2 * * 0 $HOME/backup-homeassistant.sh") | crontab -

This creates a compressed backup of your Home Assistant configuration directory every Sunday at 2 AM. If the backup fails, check that tar is installed and that you have sufficient disk space.

Restoring from Backup#

If you need to restore from a backup:

tar -xzf ~/homeassistant/backups/homeassistant-config-TIMESTAMP.tar.gz -C ~/homeassistant

Replace TIMESTAMP with the actual timestamp of your backup file. If the restore fails, ensure the backup file exists and is not corrupted.

Common Issues and Solutions#

Here are some common issues users face when installing and running Home Assistant on Ubuntu:

Cannot Access Home Assistant Web Interface#

Symptoms: Cannot connect to Home Assistant at http://YOUR_SERVER_IP:8123

Diagnostic Command:

curl -v http://localhost:8123

Solutions:

1. Check if Home Assistant is running: # For Docker: docker ps | grep homeassistant # For systemd service: sudo systemctl status [email protected]
2. Check firewall settings: sudo ufw status
3. Ensure the correct ports are open if using Docker: docker run -d \ --name=homeassistant \ --network=host \ # Important for device discovery -v ~/homeassistant/config:/config \ ghcr.io/home-assistant/home-assistant:stable

Home Assistant Container Starts But Crashes#

Symptoms: Container shows as running then stops after a few seconds

Diagnostic Command:

docker logs homeassistant

Solutions:

1. Check permissions on config directory: sudo chown -R $(id -u):$(id -g) ~/homeassistant/config
2. Ensure enough memory is available: free -h
3. Try starting with a clean configuration: mv ~/homeassistant/config ~/homeassistant/config.bak mkdir -p ~/homeassistant/config docker restart homeassistant

Z-Wave or Zigbee Devices Not Detected#

Symptoms: USB devices connected to the host are not detected in Home Assistant

Diagnostic Command:

ls -l /dev/tty*

Solutions:

1. Add the correct device mapping to Docker: docker stop homeassistant docker rm homeassistant docker run -d \ --name=homeassistant \ --restart=unless-stopped \ --network=host \ -v ~/homeassistant/config:/config \ -v /etc/localtime:/etc/localtime:ro \ --device=/dev/ttyACM0:/dev/ttyACM0 \ # Adjust device path as needed ghcr.io/home-assistant/home-assistant:stable
2. Add your user to the dialout group: sudo usermod -aG dialout $USER # Log out and back in for this to take effect

Database Errors After Upgrade#

Symptoms: Database-related errors in Home Assistant logs after upgrading

Diagnostic Command:

# For Docker:
docker logs homeassistant | grep -i database

# For direct installation:
sudo journalctl -fu [email protected] | grep -i database

Solutions:

1. Check database file permissions: sudo chown -R homeassistant:homeassistant ~/homeassistant/config/home-assistant_v2.db*
2. Create a backup before attempting repairs: cp ~/homeassistant/config/home-assistant_v2.db ~/homeassistant/config/home-assistant_v2.db.bak

Maintenance Procedures#

Keeping your Home Assistant installation updated and properly maintained is essential for security and stability.

Updating Home Assistant#

For Docker Installations#

# Pull the latest image
docker pull ghcr.io/home-assistant/home-assistant:stable

# Stop and remove the current container
docker stop homeassistant
docker rm homeassistant

# Start a new container with the latest image
docker run -d \
  --name=homeassistant \
  --restart=unless-stopped \
  --network=host \
  -v ~/homeassistant/config:/config \
  -v /etc/localtime:/etc/localtime:ro \
  ghcr.io/home-assistant/home-assistant:stable

If you're using Docker Compose:

cd ~/
docker compose pull
docker compose up -d

Always create a backup before updating. If the update fails, you can revert to the previous version by specifying the exact image tag.

For Direct Installations#

sudo systemctl stop [email protected]
sudo -u homeassistant -H -s
cd /srv/homeassistant
source bin/activate
pip3 install --upgrade homeassistant
exit
sudo systemctl start [email protected]

Monitoring Home Assistant#

Install monitoring tools to keep track of your Home Assistant instance:

sudo apt install -y htop iotop

Monitor system resources:

htop

Monitor disk I/O:

sudo iotop

View Home Assistant logs:

# For Docker:
docker logs -f homeassistant

# For direct installation:
sudo journalctl -fu [email protected]

Conclusion#

You've now successfully installed and secured Home Assistant on your Ubuntu 20.04+ system. Whether you chose the Docker method for flexibility, the VM approach for isolation, or direct installation for simplicity, you now have a powerful home automation platform at your fingertips.

Remember to keep your system and Home Assistant updated regularly, create backups before making significant changes, and refer to the official Home Assistant documentation for detailed information about specific integrations and features.

With Home Assistant, you're well on your way to creating a smarter, more automated home that respects your privacy and works exactly the way you want it to.