Home Assistant

Use it when:

• You own devices from several brands and want one place to control them.
• You want rules that go beyond what each app allows, such as "turn everything off when the last person leaves".
• You care about privacy and want data to stay at home.
• You like to tinker and want to add an AI assistant or a voice control later.

Skip it when you have two bulbs and one app is enough. Home Assistant rewards a little setup time.

Typical first projects for beginners:

• A dashboard with every light and plug.
• A sunset rule that turns on the porch light.
• A phone notification when a door or window sensor opens.
• A daily report of room temperatures.

Home Assistant has four ways to install. For a first try, pick one:

1. Home Assistant OS: a ready-made system that takes over a Raspberry Pi or mini PC. Easiest, and it includes add-ons (small extra apps) with one click.
2. Container (Docker): Home Assistant runs as one container on a machine you already have. Best if you use Docker already, or run a NAS or home server. This handbook shows this way next.
3. Supervised and Core: for experts. Skip them for now.

What you need for the Docker way:

• A computer that stays on: Linux is best (a mini PC, a Raspberry Pi, a NAS).
• Docker installed. If you are new to it, read the Docker handbook first.
• Your devices and phone on the same home network.
• About 10 minutes.

New to containers? Read the Docker handbook first, then come back. You only need the two commands below.

Step 1. Make a folder for Home Assistant's settings. Everything you configure lives here, so it survives updates.

mkdir -p ~/homeassistant/config
cd ~/homeassistant

Step 2. Create a file named compose.yaml in that folder:

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

Change TZ to your own time zone, for example America/Toronto or Asia/Shanghai.

What each line does:

• image: the official Home Assistant program. stable means the latest released version.
• ./config:/config: keeps your settings in the folder you made, outside the container.
• restart: unless-stopped: starts it again after a reboot.
• network_mode: host: lets Home Assistant find devices on your home network. This is why it works best on Linux.
• privileged: true: lets it reach USB devices such as a Zigbee stick.

Step 3. Start it:

docker compose up -d

The first start downloads the image, so wait a few minutes.

Step 4. Open it in a browser: http://<your-computer-ip>:8123 (for example http://192.168.1.20:8123). Create the owner account, set your home location, and Home Assistant will list the devices it already found.

Step 5. Update later:

docker compose pull
docker compose up -d

Mac or Windows with Docker Desktop? network_mode: host does not work the same way there, so remove that line and the privileged line, and add ports: - "8123:8123" instead. It runs, but it cannot discover devices on your network by itself. For a real home setup, use a small Linux machine.

The Docker way has no add-on store. Add-ons come only with Home Assistant OS or Supervised. With Docker you add the same tools as extra containers.

• Add devices: Settings → Devices & services → Add integration. Pick your brand and follow the steps.
• Build a dashboard: open the dashboard, press the pencil, and add cards for the things you check most. Fewer cards is better.
• Make an automation: Settings → Automations → Create. Choose a trigger (sunset, a door opens), an optional condition, and an action (turn on a light). Start with one rule.
• Install the phone app: sign in to your Home Assistant address. It gives you remote control, notifications and the phone's location.
• Back up: copy the config folder to another disk now and then, or use Settings → System → Backups.
• Update: once a month is plenty. Read the release notes before big updates, because a few integrations change.

• Do not open port 8123 to the internet as it is. Anyone could try to log in. Use Home Assistant Cloud, a VPN, or a reverse proxy with HTTPS and a strong password.
• Forgetting the config folder. If you did not map /config, your settings are gone when the container is removed.
• The wrong time zone. Sunset rules fire at the wrong time. Check TZ.
• Wi-Fi only machine. A server on Wi-Fi can drop out. Use a cable if you can.
• Updating without a backup. Make a copy of config first.
• Too many integrations at once. Add one, check it works, then add the next.
• Cloud-only devices. Some brands only work through their own cloud and may stop at any time. Prefer devices that work locally.

Once Home Assistant runs, the next steps are rules that save you time and tools that make it smarter.