How to Install Home Assistant

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.

Choose your installation method

There are two main ways to run it:

Home Assistant OS (HAOS) — a dedicated appliance install (on a mini PC, Raspberry Pi, or a VM). This is the recommended method because it supports Add-ons (one-click extras like Mosquitto, Node-RED, ESPHome) and the Supervisor.
Home Assistant Container — the Docker image. Lightweight and great if your server already runs Docker, but it does not support Add-ons; you run those as separate containers.

This tutorial covers the Container method, which fits most home servers, and notes where HAOS differs.

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/broadcast). Start it:

docker compose up -d

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.

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/Plex).
Weather and presence detection.

Prefer integrations that work locally over cloud ones where possible — they're faster and keep working offline.

Step 4: Consider MQTT and ESPHome

For serious local control, two add-ons/containers are worth it:

Mosquitto (MQTT broker) — the messaging backbone for many sensors and Zigbee/Z-Wave 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.

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.

Step 6: Remote access and backups

Remote access: don't expose port 8123 directly. Use a VPN or a reverse proxy with HTTPS and strong auth.
Backups: HAOS has built-in backups; with the Container method, back up the ./config folder regularly as part of your backup strategy.

Troubleshooting

Devices not discovered — use network_mode: host, or manually add the integration by IP.
Restart loop — check config/home-assistant.log; a bad YAML edit is the usual cause.
Slow UI on a Pi — move the database to MariaDB or a faster disk.

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.