🏠 How to Install Home Assistant on Ubuntu Server

IT & Systems
, , , ,
1

:house: How to Install Home Assistant on Ubuntu Server

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

:wrench::globe_with_meridians::house_with_garden::locked:

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’s completely free and open source.

Let’s get it installed.

:brain: 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.

What makes it special:

  • 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

:clipboard: What You’ll 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:

Time Required:

  • Fresh install: 30-45 minutes

  • Add integrations and configure: varies by complexity

:bullseye: Installation Overview

We’ll be installing Home Assistant using Docker because it:

  • Makes updates simple

  • Keeps Home Assistant isolated from your system

  • Works on any Ubuntu version

  • Makes backup and restore easy

Here’s what we’ll do:

  1. Update your system

  2. Install Docker

  3. Set up firewall rules

  4. Create Home Assistant directory structure

  5. Deploy Home Assistant with Docker Compose

  6. Access and configure the web interface

Step 1: Update Your System

First, make sure your Ubuntu installation is fully updated.


# Update package lists and upgrade all packages

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

# Remove unnecessary packages

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 don’t 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.

Important: Log out and log back in for the docker group membership to take effect:


exit

Then SSH back in and 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 - Don’t 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'

How to find your network 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 192.168.0.100, your subnet is 192.168.0.0/24

  • If your server’s IP is 10.0.0.25, your subnet is 10.0.0.0/24

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

  • Port 8123 allowed from your LAN

Step 4: Create Directory Structure

Home Assistant needs a place to store its configuration files.


# Create config directory

sudo mkdir -p /opt/homeassistant/config

# Set ownership to your user

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. You’ll see lots of output. 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:

  1. Create Admin Account

  • Choose a username

  • Create a strong password

  • Enter your name (can be anything)

  1. 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)

  1. Share Analytics (Optional)

  • Choose whether to share anonymous usage data with Home Assistant

  • This helps developers improve the platform

  • Your choice won’t affect functionality

  1. Finish Setup

  • Click “Finish”

  • You’ll see the Home Assistant dashboard

Step 9: Basic Configuration

Set a Static IP (If Not Already Done)

If your server doesn’t 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:

  1. Click Settings (gear icon in sidebar)

  2. Click System

  3. Click General

  4. Verify Time Zone is correct

  5. Click Save if you made changes

Step 10: Install Your First Integration

Let’s test Home Assistant by adding a simple integration.

  1. Click Settings (gear icon)

  2. Click Devices & Services

  3. Click + ADD INTEGRATION (bottom right)

  4. Search for “Sun”

  5. Click Sun in the results

  6. Click Submit

The Sun integration tracks sunrise/sunset times based on your location. You’ll now see a sun entity on your dashboard showing whether it’s 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 Home Assistant

From Web Interface:

  1. Go to Settings > System

  2. Click Restart (top right)

  3. Choose Restart Home Assistant

From Command Line:


cd /opt/homeassistant

docker compose restart

Stop Home Assistant


cd /opt/homeassistant

docker compose down

Start Home Assistant


cd /opt/homeassistant

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.

Automated backups can be configured later using Home Assistant’s built-in backup feature or external backup tools.

Troubleshooting

Home Assistant Won’t Start

Check container logs:


docker logs homeassistant

Look for error messages. Common issues:

  • Port 8123 already in use

  • Permission issues with config directory

  • Corrupted configuration file

Verify Docker is running:


sudo systemctl status docker

Can’t Access Web Interface

Check if container is running:


docker ps

If you don’t 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

You should see something like:


tcp6 0 0 :::8123 :::* LISTEN 12345/python3

If not, Home Assistant isn’t running properly. Check logs.

Try from server itself:


curl http://localhost:8123

If this works but you can’t access from another computer, it’s a firewall/network issue.

Configuration Errors

If you edited configuration files and Home Assistant won’t start:

  1. Check the logs for specific error messages

  2. Validate your YAML syntax (indentation matters!)

  3. 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

Check disk usage:


df -h /opt/homeassistant

Clean up old logs and database:

Home Assistant stores history in an SQLite database that can grow large over time. You can purge old data from the web interface:

  1. Go to Settings > System > Storage

  2. Adjust history retention

  3. Click Purge

Or limit retention in /opt/homeassistant/config/configuration.yaml:


recorder:

purge_keep_days: 7

Then restart Home Assistant.

Next Steps

Now that Home Assistant is running, here’s what to explore next:

1. Add Devices and Integrations

Home Assistant supports thousands of devices. Popular categories:

  • Lights: Philips Hue, LIFX, TP-Link, Yeelight

  • Cameras: Most IP cameras, webcams

  • Smart Plugs: TP-Link, Wemo, Sonoff

  • Thermostats: Nest, Ecobee, Honeywell

  • Voice Assistants: Google Home, Alexa

  • Media Players: Roku, Chromecast, Plex, Spotify

Browse integrations at Settings > Devices & Services > Add Integration.

2. 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.

3. Set Up External Access

Access Home Assistant from anywhere:

  • Set up a reverse proxy with SSL (recommended)

  • Use Home Assistant Cloud (paid, easiest)

  • Use a VPN to your network (most secure)

External access requires proper security measures. Research before exposing Home Assistant to the internet.

4. Install Add-ons and HACS

Home Assistant has an add-on ecosystem for extended functionality. You’ll need to switch to Home Assistant Supervised or Home Assistant OS to use official add-ons, but you can install HACS (Home Assistant Community Store) for custom integrations:

Visit: https://hacs.xyz/

5. Explore Dashboards

Customize your interface:

  • Create multiple dashboards for different rooms or users

  • Add cards for quick access to common controls

  • Use custom card designs from the community

6. Join the Community

Home Assistant has an active community:

Security Best Practices

Change Default Ports (Optional)

If exposing Home Assistant to the internet, consider changing from port 8123 to something non-standard.

Edit docker-compose.yml:


ports:

- "8123:8123"

Change to:


ports:

- "12345:8123"

Then restart:


docker compose down

docker compose up -d

Access on new port: http://YOUR_IP:12345

Enable Two-Factor Authentication

  1. Go to your profile (click your name, bottom left)

  2. Scroll to Two-factor Authentication

  3. Follow setup instructions

Use Strong Passwords

Generate a secure password:


openssl rand -base64 32

Save it in a password manager.

Regular Updates

Check for updates monthly:


cd /opt/homeassistant

docker compose pull

docker compose up -d

Network Isolation (Advanced)

Consider putting IoT devices on a separate VLAN to isolate them from your main network. This is beyond the scope of this guide but worth researching for enhanced security.

Performance Tips

Reduce Database Size

Limit what gets recorded:

Edit /opt/homeassistant/config/configuration.yaml:


recorder:

purge_keep_days: 7

exclude:

domains:

- automation

- updater

entities:

- sensor.weather_temperature

Use MariaDB Instead of SQLite (Advanced)

For larger installations, switching to MariaDB improves performance. This requires running a separate database container. Research this once you have hundreds of entities.

Monitor Resource Usage

From Home Assistant, install the System Monitor integration to track:

  • CPU usage

  • Memory usage

  • Disk space

  • Network activity

Complete - You’re Done!

You now have a fully functional Home Assistant installation running on Ubuntu Server.

What you’ve accomplished:

  • :white_check_mark: Installed Docker

  • :white_check_mark: Configured firewall security

  • :white_check_mark: Deployed Home Assistant

  • :white_check_mark: Set up basic configuration

  • :white_check_mark: Learned management commands

Your Home Assistant is:

  • Running 24/7

  • Accessible from your local network

  • Ready to integrate with smart home devices

  • Automatically restarting after reboots or crashes

Start adding devices, creating automations, and taking control of your smart home.

:speech_balloon: Questions or Issues?

Run into problems during installation? Have questions about integrations or automations?

Drop a comment below. Let’s troubleshoot together.