---

Objective

Install Home Assistant on an Ubuntu Server using Docker so it is easy to maintain, cleanly containerised, and portable for future upgrades or migrations.

---

System Overview

Hardware:

• Dell OptiPlex small form factor
• Intel i5 (4th gen)
• 16GB RAM
• 250GB SSD

Operating System:

• Ubuntu Server 22.04 LTS

Networking:

• Static IP assigned via router DHCP reservation
• Hostname: homelab

Goal:
Run Home Assistant in Docker using Docker Compose.

---

Prerequisites

Update operating system and packages

sudo apt update && sudo apt upgrade -y

Install Docker and Docker Compose

sudo apt install docker.io docker-compose -y
sudo systemctl enable docker
sudo systemctl start docker

Using the Ubuntu repository packages keeps things simple. If the very latest Docker features are required, use Docker’s official installation method.

---

Folder Structure

All homelab services are stored under /opt for clarity and backup consistency.

sudo mkdir -p /opt/homeassistant
cd /opt/homeassistant

Reasons:

• Keeps services organised
• Simplifies backups
• Easy to migrate to a new machine

---

docker-compose.yml

Create the compose file:

sudo nano /opt/homeassistant/docker-compose.yml

Paste the following:

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
    environment:
      - TZ=Europe/London
    network_mode: host
    restart: unless-stopped

Notes

• Host networking allows Home Assistant to automatically detect local devices such as smart bulbs and hubs.
• /opt/homeassistant/config stores all user data, integrations, automations and backups.
• The restart policy ensures the container returns after system reboots or crashes.

---

Start Home Assistant

sudo docker-compose up -d

Verify the container is running:

sudo docker ps

Home Assistant should then be accessible at:

http://YOUR_SERVER_IP:8123

Example:

http://192.168.0.10:8123

The setup wizard will appear on the first launch.

---

Updating Home Assistant

Pull the latest image

cd /opt/homeassistant
sudo docker-compose pull

Relaunch the container

sudo docker-compose up -d

Check logs

sudo docker logs homeassistant --tail 100

Review release notes for breaking changes before updating.

---

Backups

Simple rsync backup of the configuration directory:

sudo rsync -avz /opt/homeassistant/config /media/backups/homeassistant/

For riskier changes or upgrades, take a full snapshot:

sudo cp -r /opt/homeassistant/config /opt/backups/config-$(date +%Y-%m-%d)

---

Troubleshooting

Devices not appearing in Home Assistant

Ensure host networking is in use.

docker inspect homeassistant | grep -i "network"

Port 8123 already in use

Find the existing process:

sudo lsof -i:8123

Stop the process or change the container port.

Permissions errors in the config directory

sudo chown -R 1000:1000 /opt/homeassistant/config

---

Notes

• Host networking provides the easiest starting point because device discovery works without additional configuration.
• Home Assistant expands quickly; version controlling the /config directory prevents painful recovery work.
• Using Docker keeps the OS clean and avoids dependency conflicts common with manual installations.