Skip to content
TutorialsAutomationIntermediate

How to Install Home Assistant

Install Home Assistant for private, local-first smart home automation: HAOS vs Container, Docker Compose, integrations, Zigbee and MQTT, automations, backups and remote access.

by HomeServersGuide TeamUpdated November 3, 20265 min read

What you'll build

Home Assistant is the most powerful open-source home-automation platform. It connects thousands of smart devices and runs your automations locally, so your home keeps working even when the internet or a vendor's cloud is down — and your data stays yours. It replaces a pile of separate manufacturer apps with a single dashboard and a rules engine.

Choose your installation method

There are several ways to run it, and the choice is the most important decision:

MethodWhat it isAdd-onsBest for
Home Assistant OS (HAOS)A dedicated appliance image on a mini PC, Raspberry Pi or VMYesMost people; easiest, fully supported
ContainerThe Docker imageNo (run extras as containers)Servers that already run Docker
Supervised / CoreAdvanced installsVariesExperts; limited support

Recommendation: if you can dedicate a small machine or a virtual machine, HAOS is the best experience. It manages updates, backups and add-ons (Mosquitto, Node-RED, ESPHome, Zigbee2MQTT and more) for you. A common pattern is to run HAOS as a VM on Proxmox, alongside your Docker host. If your home server is mainly a Docker box, the Container method fits well and is what this tutorial covers.

Hardware notes

Home Assistant itself is light; a Raspberry Pi 4 or an Intel N100 mini PC is plenty. Prefer an SSD to an SD card, because the database writes constantly. If you use Zigbee or Z-Wave devices, you'll also need a USB radio dongle; use a short USB extension cable to keep it away from USB 3 interference. See our hardware guide and single-board computers.

Step 1: Deploy the container

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    privileged: true
    network_mode: host
    volumes:
      - ./config:/config
      - /run/dbus:/run/dbus:ro
    environment:
      - TZ=Europe/Paris

network_mode: host is used so Home Assistant can discover devices on your LAN (many integrations rely on mDNS and broadcast). privileged: true helps with Bluetooth and some USB devices; if you don't need those, you can try removing it and pass specific devices instead (for example devices: - /dev/ttyUSB0:/dev/ttyUSB0). Start it:

docker compose up -d
docker compose logs -f homeassistant

Step 2: Onboarding

Open http://your-server-ip:8123. Create your account, name your home, and set your location (used for sunrise/sunset automations and weather). Home Assistant will already suggest devices it discovered on your network. Give the server a fixed address (see the networking guide) so integrations don't break.

Step 3: Add integrations

Go to Settings → Devices & Services → Add Integration. Start small — add one or two things you'll actually use:

  • Smart plugs or bulbs (many work locally via their brand integration).
  • A media player (Chromecast, Sonos, your Jellyfin or Plex).
  • Weather and presence detection.

Prefer integrations that work locally over cloud ones where possible — they're faster and keep working offline. Check the "IoT class" in each integration's documentation: "local polling" and "local push" are the ones you want.

Step 4: Zigbee, Z-Wave, MQTT and ESPHome

For serious local control, a few building blocks are worth knowing:

  • Zigbee — low-power mesh for sensors, bulbs and switches. Use a coordinator dongle with ZHA (built in) or Zigbee2MQTT.
  • MQTT broker (Mosquitto) — the messaging backbone for many sensors and bridges.
  • ESPHome — flash cheap ESP32 devices into powerful, fully local sensors.

On HAOS these are one-click Add-ons; with the Container method, run them as their own containers, for example Mosquitto:

  mosquitto:
    image: eclipse-mosquitto:2
    restart: unless-stopped
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data

Version 2 of Mosquitto requires a config file that enables a listener and authentication, so add a mosquitto.conf before starting it.

Step 5: Your first automation

Automations are where Home Assistant shines. In Settings → Automations, create one with the visual editor:

  • Trigger: sunset.
  • Condition: someone is home.
  • Action: turn on the living-room lights at 40% brightness.

Start with a few reliable automations before building elaborate ones — trust is earned when the basics always work. Use areas and labels from the start to keep things organised, and give devices clear names. Dashboards (Lovelace) can be customised later.

Step 6: Remote access, security and backups

  • Remote access: don't expose port 8123 directly. Use a VPN or a reverse proxy with HTTPS and strong auth. If you use a proxy, add its address to trusted_proxies in the Home Assistant http: configuration. See the secure remote access guide.
  • Strong accounts: enable multi-factor authentication for every user.
  • Backups: HAOS has built-in backups you can send to another location; with the Container method, back up the ./config folder regularly as part of your backup strategy, and test a restore.
  • Database size: the recorder keeps history for 10 days by default; reduce it, or exclude noisy entities, if the database grows too large.

Step 7: Keep it healthy

  • Read the release notes before each monthly update, because breaking changes are announced there.
  • Back up before updating.
  • Remove unused integrations and devices.
  • Monitor Home Assistant with Uptime Kuma.

Troubleshooting

  • Devices not discovered — use network_mode: host, or manually add the integration by IP. Check that your switch or Wi-Fi isn't blocking multicast between VLANs.
  • Restart loop — check config/home-assistant.log; a bad YAML edit is the usual cause. Use Developer tools → Check configuration before restarting.
  • Slow UI on a Pi — move to an SSD, reduce recorder history, or switch the database to MariaDB.
  • Zigbee dongle not found — confirm the device path with ls /dev/serial/by-id/ and pass it into the container.
  • Integration offline after router change — devices got new IP addresses; set DHCP reservations.

Next steps

Once comfortable, add Frigate for local AI camera detection and a dashboard on a wall tablet. Home Assistant grows with you — resist the urge to automate everything on day one.

Related articles

TutorialsAutomationBeginner

How to Install Uptime Kuma

Install Uptime Kuma with Docker to monitor your homelab services, get alerts on your phone, track backup jobs with push monitors and publish a status page.

5 min read
TutorialsAutomationIntermediate

How to Set Up Grafana and Prometheus

Stand up a metrics stack with Prometheus, node_exporter, cAdvisor and Grafana to visualize your home server's health, with retention, security and alerting tips.

4 min read
TutorialsMedia ServersBeginner

How to Set Up Jellyseerr for Media Requests

Install Jellyseerr with Docker, connect it to Jellyfin, Sonarr and Radarr, and set up users, quotas and approvals so your household can request media on its own.

4 min read