Welcome to the Smart Home

This month you build a real smart home from scratch, one that is entirely yours, using a Raspberry Pi 5, the open-source Home Assistant platform, and Zigbee devices. This first lesson sets it up: you will install Home Assistant with Docker, connect a Zigbee coordinator, and stand up a private smart-home hub with no cloud and no data mining. By the end you own the brain of your smart home.

Why self-host your smart home

Commercial platforms like Amazon Alexa or Google Home are convenient, but they trade away privacy and control: your data flows to their servers, and there have been real cases of employee access to camera feeds and of users being locked out of their own homes. Home Assistant is different. It is open source and runs entirely on your Pi, so there is no cloud middleman, no data mining, and no outside eyes. Your home stays yours, which is the whole point of building it this way.

The pieces of the system

Two things make this work. Home Assistant is the brain, the software hub that runs your smart home and gives you a dashboard. The Zigbee USB coordinator is the radio: a small dongle you plug into the Pi that lets it talk to Zigbee sensors, buttons, bulbs, and plugs. You install Home Assistant on top of the Raspberry Pi OS you already have, using Docker so it lives alongside your existing setup without disturbing it.

Why Docker

Docker runs Home Assistant in a self-contained container on your existing Raspberry Pi OS, rather than reinstalling the whole system. That means you keep all of last month's work and can keep using the Pi for other things, while Home Assistant runs cleanly in its own space. It is the tidy way to add a big application without taking over the machine.

Zigbee and the mesh network

Zigbee is a communications standard made for home devices, and it is different from Wi-Fi. Its key trait is that it forms a mesh network: each mains-powered device also relays for others, so every new bulb or plug you add actually strengthens the whole network and extends its range. That makes Zigbee reliable and efficient for lots of small IoT devices, which is why it is the backbone of this build. In Home Assistant you enable it through the ZHA (Zigbee Home Automation) integration.

Working through it

Install Docker. On the Pi, install Docker with the official script, then add your user to the docker group so you can run it without extra permissions, and install Docker Compose.

Create the Home Assistant folder and compose file. Make a home assistant directory, move into it, and create a docker-compose.yml describing the Home Assistant container, pointing it at your Zigbee coordinator's device port.

Start Home Assistant. Run docker compose up -d and wait a minute or two for it to come up.

Open the dashboard and onboard. Browse to localhost:8123 on the Pi, or the Pi's IP address and port 8123 from another device. Create your account and set your home's name, location, and time zone.

Enable Zigbee. Go to Settings, then Devices and Services, add the ZHA integration, select the coordinator's port (often /dev/ttyUSB0 or /dev/ttyACM0), and submit. You now have a working Zigbee hub.

Customize the dashboard. Add a few cards and name your dashboard something like mission control; this is where lights, plugs, and sensors will appear as you add them this month.

Install Docker and start Home Assistant

# install Docker
curl -fsSL https://get.docker.com | sh

# let your user run Docker, then log out and back in
sudo usermod -aG docker $USER

# install Docker Compose, then set up Home Assistant
mkdir homeassistant && cd homeassistant
nano docker-compose.yml   # paste the compose config below

# bring it up (wait 1-2 minutes)
docker compose up -d
# then open http://localhost:8123

These commands install Docker, grant your user access, and launch Home Assistant in a container. After it starts, the dashboard is served locally on port 8123.

docker-compose.yml for Home Assistant

services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./config:/config
    devices:
      # your Zigbee coordinator; may be /dev/ttyACM0 instead
      - /dev/ttyUSB0:/dev/ttyUSB0

This describes the Home Assistant container and, crucially, passes the Zigbee coordinator's device through so Home Assistant can use it. If your dongle appears as ttyACM0, change the device line to match.

Common mistakes and troubleshooting

The Zigbee integration cannot find the coordinator.