How to Install Home Assistant on Ubuntu Server

Privacy & Self-Hosting December 25, 2025

Take control of your smart home with a self-hosted automation platform

Tired of cloud-dependent smart home platforms that go offline when the internet drops? Want complete control over your home automation without monthly fees or privacy concerns?

Home Assistant gives you local control over all your smart devices, powerful automation capabilities, and works even when your internet is down. Best of all, it is completely free and open source.

What is Home Assistant?

Home Assistant is an open-source home automation platform that runs locally on your hardware. It connects to hundreds of different smart home devices and services, giving you one unified interface to control everything.

Local control - Your home, your hardware, your data
Works offline - Internet down? Your automations keep running
Device agnostic - Supports 2,000+ integrations (lights, cameras, thermostats, sensors, etc.)
Powerful automations - Control your home based on time, conditions, or events
No monthly fees - Free forever, no subscriptions required

What You Will Need

Prerequisites

Required:

Ubuntu Server installed and fully updated (20.04 LTS, 22.04 LTS, or 24.04 LTS)
SSH access to your server
Root or sudo privileges
At least 2GB RAM (4GB recommended)
20GB available disk space (60GB recommended for recordings and history)

Network Requirements:

Static IP address for your server (set in your router's DHCP settings)
Port 8123 available for Home Assistant web interface

Optional but Recommended:

Domain name or DuckDNS subdomain for external access
SSL certificate for HTTPS (can set up later)

Time Required: Fresh install takes 30-45 minutes. Adding integrations and configuring varies by complexity.

Installation Overview

We will be installing Home Assistant using Docker because it makes updates simple, keeps Home Assistant isolated from your system, works on any Ubuntu version, and makes backup and restore easy.

Here is what we will do:

Update your system
Install Docker
Set up firewall rules
Create Home Assistant directory structure
Deploy Home Assistant with Docker Compose
Access and configure the web interface

Step 1: Update Your System

First, make sure your Ubuntu installation is fully updated.

sudo apt update && sudo apt -y full-upgrade

sudo apt -y autoremove --purge && sudo apt -y autoclean

If the kernel was updated, reboot:

sudo reboot

Wait about 60 seconds, then SSH back into your server.

Step 2: Install Docker

Docker is the foundation for running Home Assistant in a container.

Install prerequisites:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

Add Docker's official GPG key:

sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc

sudo chmod a+r /etc/apt/keyrings/docker.asc

Add Docker repository:

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Configure Docker permissions:

Add your user to the docker group so you do not need sudo for every docker command:

sudo usermod -aG docker $USER

Enable Docker to start on boot:

sudo systemctl enable docker
sudo systemctl start docker

Verify Docker installation:

sudo docker run hello-world

You should see a message confirming Docker is working correctly.

Group Membership

Log out and log back in for the docker group membership to take effect. Then verify you can run docker without sudo: docker ps. You should see an empty list of containers (no error message).

Step 3: Configure Firewall

Secure your server while allowing Home Assistant access.

Enable UFW firewall:

sudo ufw enable

Type y when prompted.

Set default policies:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw default deny routed

Allow SSH (Critical - Do Not Lock Yourself Out!):

Replace 192.168.1.0/24 with your actual network subnet.

sudo ufw allow from 192.168.1.0/24 to any port 22 proto tcp comment 'SSH from LAN'

Finding Your Subnet

If your server's IP is 192.168.1.50, your subnet is 192.168.1.0/24. If your server's IP is 10.0.0.25, your subnet is 10.0.0.0/24. The /24 means "the first three octets stay the same."

Allow Home Assistant web interface:

sudo ufw allow from 192.168.1.0/24 to any port 8123 proto tcp comment 'Home Assistant Web UI'

Again, replace 192.168.1.0/24 with your network subnet.

Verify firewall rules:

sudo ufw status verbose

You should see default policies (deny incoming, allow outgoing), SSH allowed from your LAN, and port 8123 allowed from your LAN.

Step 4: Create Directory Structure

Home Assistant needs a place to store its configuration files.

sudo mkdir -p /opt/homeassistant/config

sudo chown -R $USER:$USER /opt/homeassistant

Step 5: Create Docker Compose File

Docker Compose lets you define and manage your Home Assistant container with a simple configuration file.

nano /opt/homeassistant/docker-compose.yml

Add this content:

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    privileged: true
    network_mode: host

What this does:

container_name: Names the container "homeassistant"
image: Uses the official Home Assistant stable release
volumes: Maps config directory and syncs system time
restart: Automatically restarts if crashed or after reboot
privileged: Gives Home Assistant access to hardware (needed for some integrations)
network_mode: host: Uses your server's network directly (simplifies setup)

Save and exit: Press Ctrl+O, then Enter, then Ctrl+X.

Step 6: Start Home Assistant

cd /opt/homeassistant
docker compose up -d

The -d flag runs it in detached mode (background).

Wait 2-3 minutes for Home Assistant to fully start. First startup takes longer as it downloads dependencies and initializes the database.

Step 7: Verify Home Assistant is Running

Check container status:

docker ps

You should see a container named homeassistant with status Up.

Check logs:

docker logs homeassistant

Look for messages indicating Home Assistant is starting. Near the end, you should see something like:

INFO (MainThread) [homeassistant.core] Starting Home Assistant
INFO (MainThread) [homeassistant.bootstrap] Home Assistant initialized in X.XXs

If you see errors, wait another minute and check again. First startup can take 3-5 minutes on slower hardware.

Step 8: Access Home Assistant Web Interface

Open your web browser and navigate to:

http://YOUR_SERVER_IP:8123

Replace YOUR_SERVER_IP with your server's actual IP address. For example: http://192.168.1.50:8123

First-time Setup Wizard:

Create Admin Account - Choose a username and create a strong password
Set Your Location - Enter your home address or move the map pin. This sets your timezone and enables location-based automations. Choose your unit system (Imperial/Metric).
Share Analytics (Optional) - Choose whether to share anonymous usage data with Home Assistant. Your choice will not affect functionality.
Finish Setup - Click "Finish" and you will see the Home Assistant dashboard

Step 9: Basic Configuration

Set a Static IP (If Not Already Done)

If your server does not have a static IP, set one in your router's DHCP settings to prevent the IP from changing. Look for "DHCP Reservation" or "Static DHCP" in your router's admin interface.

Configure Time Zone (If Needed)

Home Assistant should auto-detect your timezone, but verify:

Click Settings (gear icon in sidebar)
Click System
Click General
Verify Time Zone is correct
Click Save if you made changes

Step 10: Install Your First Integration

Let us test Home Assistant by adding a simple integration.

Click Settings (gear icon)
Click Devices and Services
Click + ADD INTEGRATION (bottom right)
Search for "Sun"
Click Sun in the results
Click Submit

The Sun integration tracks sunrise/sunset times based on your location. You will now see a sun entity on your dashboard showing whether it is day or night.

Other beginner-friendly integrations to try:

Weather - Get local weather forecasts
Speedtest - Monitor your internet speed
System Monitor - Track your server's CPU, memory, and disk usage

Managing Home Assistant

View Logs

docker logs homeassistant

# Follow logs in real-time
docker logs -f homeassistant

Press Ctrl+C to stop following.

Restart

From Web Interface: Go to Settings > System > click Restart (top right) > choose Restart Home Assistant

From Command Line:

cd /opt/homeassistant
docker compose restart

Stop and Start

cd /opt/homeassistant

# Stop
docker compose down

# Start
docker compose up -d

Update Home Assistant

cd /opt/homeassistant
docker compose pull
docker compose up -d

This pulls the latest stable image and recreates the container. Your configuration is preserved in /opt/homeassistant/config.

Backup Your Configuration

Create a manual backup:

cd /opt/homeassistant
sudo tar -czf ~/ha-backup-$(date +%Y%m%d).tar.gz config/

This creates a timestamped backup file in your home directory.

Restore from backup:

cd /opt/homeassistant
sudo tar -xzf ~/ha-backup-YYYYMMDD.tar.gz
docker compose restart

Replace YYYYMMDD with your backup date.

Troubleshooting

Home Assistant Will Not Start

Check container logs:

docker logs homeassistant

Common issues: port 8123 already in use, permission issues with config directory, corrupted configuration file.

Verify Docker is running:

sudo systemctl status docker

Cannot Access Web Interface

Check if container is running:

docker ps

If you do not see homeassistant, start it:

cd /opt/homeassistant
docker compose up -d

Check firewall:

sudo ufw status verbose

Make sure port 8123 is allowed from your network.

Check if port 8123 is listening:

sudo netstat -tlnp | grep 8123

Try from the server itself:

curl http://localhost:8123

If this works but you cannot access from another computer, it is a firewall/network issue.

Configuration Errors

If you edited configuration files and Home Assistant will not start:

Check the logs for specific error messages
Validate your YAML syntax (indentation matters!)
Restore from backup if needed

Common YAML mistakes: using tabs instead of spaces, incorrect indentation, missing colons, smart quotes instead of straight quotes.

Out of Disk Space

df -h /opt/homeassistant

Home Assistant stores history in an SQLite database that can grow large over time. You can limit retention in /opt/homeassistant/config/configuration.yaml:

recorder:
  purge_keep_days: 7

Then restart Home Assistant.

Next Steps

Add Devices and Integrations

Home Assistant supports thousands of devices. Popular categories include lights (Philips Hue, LIFX, TP-Link), cameras (most IP cameras), smart plugs (TP-Link, Wemo, Sonoff), thermostats (Nest, Ecobee, Honeywell), voice assistants (Google Home, Alexa), and media players (Roku, Chromecast, Plex, Spotify). Browse integrations at Settings > Devices and Services > Add Integration.

Create Automations

Automations are what make your smart home actually smart. Examples: turn on lights at sunset, send notification when door opens, adjust thermostat based on occupancy, turn off everything when you leave. Start simple and build complexity over time.

Set Up External Access

Access Home Assistant from anywhere: set up a reverse proxy with SSL (recommended), use Home Assistant Cloud (paid, easiest), or use a VPN to your network (most secure). External access requires proper security measures. Research before exposing Home Assistant to the internet.

Install HACS

Home Assistant Community Store (HACS) provides custom integrations and themes. Visit: hacs.xyz

Security Best Practices

Enable Two-Factor Authentication - Go to your profile (click your name, bottom left) > scroll to Two-factor Authentication
Use Strong Passwords - Generate a secure password: openssl rand -base64 32 and save it in a password manager
Regular Updates - Check for updates monthly with docker compose pull
Network Isolation - Consider putting IoT devices on a separate VLAN to isolate them from your main network