Quick Setup
The fastest path from a fresh Raspberry Pi to a running Sparrow Home — five steps, no detours. For every option and every environment variable, see the full Getting Started guide.
Get the hardware
A Raspberry Pi (Ubuntu or Raspberry Pi OS), a USB Zigbee adapter, and a router with internet access. A UPS is optional but recommended.
Clone the repo
git clone git@github.com:sparrow-codes/sparrow-home.git cd sparrow-home
Create and fill in .env
.env
is a plain text file holding configuration and secrets (database password, JWT key, Zigbee port…) that the app reads
on startup, instead of having them hardcoded. It's not included in the repo — you create it yourself.
Create it in the project root — the sparrow-home folder from step 2, right next to docker-compose.yaml:
nano .env
Paste this in, then replace the placeholder values with your own (at minimum: dbPassword, jwtSecret, and the two zigbee* fields to match your adapter):
mode='production' timeZone=Europe/Warsaw dbUserName=sparrow dbPassword=sparrow dbName=sparrow_home
jwtSecret=REPLACE_WITH_RANDOM_STRING jwtExpiry=7d zigbeeSerialPort=/dev/serial/by-id/USB-your-adapter
zigbeeAdapter=zstack
Save and exit nano with Ctrl+O, Enter, then Ctrl+X. Not sure which zigbeeSerialPort to use? Run ls /dev/serial/by-id/
with your adapter plugged in — see Start the App for the full variable reference and every optional field.
Start it with Docker Compose
Docker Compose reads docker-compose.yaml
(already in the repo) and starts every piece Sparrow Home needs — database, MQTT broker, Zigbee2MQTT, backend,
frontend — each in its own container, wired together automatically. You don't install any of them yourself.
From the same sparrow-home folder, run:
docker compose -f docker-compose.yaml -p docker up -d
What this does: -f docker-compose.yaml points to the config file, -p docker names this project ("docker"), and up -d
builds/starts all containers in the background (-d
= detached, so it keeps running after you close the terminal).
Then open http://yourServerIpAddress in your browser (find the IP with hostname -I
on the Pi). First launch auto-generates the Zigbee2MQTT configuration — this can take a minute, so give it a moment
before reloading.
Keep it updated
docker compose pull docker compose up -d --remove-orphans docker image prune -f
Building Sparrow Home itself, not just running it? See Local Setup under Development instead — that's the developer path, not this one.