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.
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:
| Method | What it is | Add-ons | Best for |
|---|---|---|---|
| Home Assistant OS (HAOS) | A dedicated appliance image on a mini PC, Raspberry Pi or VM | Yes | Most people; easiest, fully supported |
| Container | The Docker image | No (run extras as containers) | Servers that already run Docker |
| Supervised / Core | Advanced installs | Varies | Experts; 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/Parisnetwork_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 homeassistantStep 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/dataVersion 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_proxiesin the Home Assistanthttp: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
./configfolder 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
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.
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.
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.