Home Assistant (HA) is an open-source platform for smart home automation that runs locally. This guide explains how to install Home Assistant Container using Docker Compose — the right choice if you want to run HA on an existing server or VM without dedicated hardware.

Installation Methods: There are several ways to install Home Assistant — Home Assistant OS (full OS, most complete), Home Assistant Supervised (on regular Linux with a supervisor), and Home Assistant Container (pure Docker, most flexible but without the Add-on Store). This guide uses the Container via Docker method.

System Requirements

  • Docker & Docker Compose already installed (see Docker installation guide)
  • Minimum 2 GB RAM (4 GB+ recommended)
  • Minimum 32 GB storage
  • OS: Ubuntu / Debian / Proxmox LXC

Installation Steps

  1. 1

    Create Directory for Home Assistant

    mkdir -p /opt/homeassistant/config
cd /opt/homeassistant
  2. 2

    Create docker-compose.yml

    Create the file /opt/homeassistant/docker-compose.yml:

    services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    Why network_mode: host? Home Assistant needs direct access to the local network for device discovery (mDNS, UPnP, etc.). Host mode allows HA to see the full network like a native application.
  3. 3

    Start Home Assistant

    cd /opt/homeassistant
docker compose up -d

# Monitor the startup process
docker compose logs -f homeassistant

    The first startup takes 2–5 minutes as HA downloads components and sets up the database.

  4. 4

    Access the Web UI

    Open your browser and navigate to Home Assistant at:

    http://<Server-IP>:8123

    On first launch, an initial setup wizard will appear.

  5. 5

    Initial Setup

    Follow the onboarding wizard:

    • Create an admin account (name, username, password)
    • Set your location (used for sunrise/sunset calculations)
    • HA will automatically detect devices on the local network
    • Click Finish to enter the dashboard

Basic Configuration

Config Directory Structure

After setup, the /opt/homeassistant/config/ directory will contain:

/opt/homeassistant/config/
├── configuration.yaml    # Main configuration
├── automations.yaml      # Automation rules
├── scripts.yaml          # Scripts
├── scenes.yaml           # Scenes
├── secrets.yaml          # Passwords & tokens (don't share!)
└── .storage/             # HA internal database

configuration.yaml

Recommended basic configuration in configuration.yaml:

homeassistant:
  name: Home
  latitude: -6.2088        # Your location coordinates
  longitude: 106.8456
  elevation: 8
  unit_system: metric
  currency: IDR
  country: ID
  language: en
  time_zone: Asia/Jakarta

# Enable HTTP with trusted proxies if behind a reverse proxy
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1

# Log level (optional, for debugging)
logger:
  default: warning

Adding Integrations

Go to Settings → Devices & Services → Add Integration to add devices. Home Assistant supports thousands of integrations including:

  • Mi Home / Xiaomi — lights, sensors, AC
  • TP-Link — smart plug, switch
  • MQTT — custom sensors (ESP32, Arduino)
  • Frigate — CCTV camera integration
  • Google / Apple Calendar
  • Telegram — bot notifications

Frigate Integration (CCTV)

If you're already running Frigate NVR, add the integration via:

  1. Settings → Devices & Services → Add Integration
  2. Search for "Frigate"
  3. Enter the Frigate URL: http://Server-IP:5000
  4. Frigate will appear as cameras and motion sensors in HA
MQTT: For a richer Frigate integration (events, notifications), enable MQTT in both Frigate and Home Assistant. Install the Mosquitto Broker addon or use an external MQTT broker.

Updating Home Assistant

cd /opt/homeassistant

# Pull the latest image
docker compose pull

# Restart with the new image
docker compose up -d

# Check version
docker exec homeassistant ha core info
Before Updating: Always create a backup first via Settings → System → Backups → Create Backup. Or manually back up the config folder: cp -r /opt/homeassistant/config /opt/homeassistant/config-backup-$(date +%Y%m%d)