Getting Started
Step-by-step instructions to get started with Sparrow Home locally.
Hardware Configuration for Sparrow Home as your personal smart home assistant
Run Sparrow Home
Update your Sparrow Home system to the latest version
Hardware Configuration
Devices
To communicate with Zigbee devices, Sparrow Home requires a compatible Zigbee adapter. If you are using Raspberry Pi, you can use the following adapters that are attached via USB. Please view the https://www.zigbee2mqtt.io/guide/adapters/ for more options.
List of devices
- Raspberry Pi (supports both Ubuntu and Raspberry Pi OS)
- Zigbee USB Stick
- Router (internet connection required)
- UPS (optional but recommended)
Consider securing your system with UPS to maintain power during outages and prevent data corruption.
Start the App
This page explains how to start Sparrow Home on your home server.
First, clone the repository from git and navigate to the project root:
git clone git@github.com:sparrow-codes/sparrow-home.git
then:
cd sparrow-home
Instead of running separate npm scripts, you only need to:
-
Add configuration files in the project root:
.env— backend environment variables
nano .env
-
Fill below content in
.envfile:
mode='production' timeZone= dbUserName= dbPassword= dbName= jwtSecret= jwtExpiry= pushPublicKey=
pushPrivateKey= pushAdminEmail= zigbeeSerialPort= zigbeeAdapter= # Optional for Tailscale VPN access - set your domain
name here if you are using Tailscale and want to access the app via DNS instead of IP address
tailscaleDomain="
| Variable | Description |
|---|---|
mode |
Application run mode. Use production for a production server.
|
timeZone |
Time zone for Sparrow Home system (e.g., Europe/Warsaw).
|
dbUserName |
Database username used to connect to the application's database. |
dbPassword |
Password for the database user. Keep this secret. |
dbName |
Name of the database to use for the application. |
jwtSecret |
Secret key used to sign JSON Web Tokens (must be kept secret). |
jwtExpiry |
Token expiration duration (e.g., 1h,
7d) or timestamp.
|
pushPublicKey |
VAPID public key for Web Push notifications. |
pushPrivateKey |
VAPID private key for Web Push notifications (keep secret). |
pushAdminEmail |
Contact email used in VAPID claims (e.g., admin@example.com).
|
zigbeeSerialPort |
Serial port path for the Zigbee adapter (e.g., /dev/serial/by-id/USB-someName). Please check Zigbee docs
|
zigbeeAdapter |
Adapter type or driver for Zigbee integration (e.g., zstack, deconz).
|
tailscaleDomain |
Your domain name, if you are connecting to Tailscale VPN - make sure it mathes your DNS. |
- Start all services with Docker Compose:
docker compose -f docker-compose.yaml -p docker up -d
This will start required infrastructure services (database, MQTT broker, Zigbee) and the application containers defined in docker-compose.yaml. After startup, open http://yourServerIpAddress or https://yourTailscaleDomain
If you are launching the app for the first time, the scripts will automatically generate configuration for
Zigbee2MQTT. This is done only once during the first launch, so if you need to change Zigbee configuration, you will
need to do it manually by editing the generated server-data/zigbee2mqtt/data/configuration.yaml
file. This can be crucial, especially when your adapter requires more advanced configuration.
System Update
It is recommended to keep your Sparrow Home system up to date to benefit from the latest features, improvements, and security patches. This guide will walk you through the process of updating your Sparrow Home system.
Remember to check for updates for your operating system as well.
Update Process
To update your Sparrow Home system, simply run the following command in your terminal:
docker compose pull docker compose up -d --remove-orphans docker image prune -f
In rare scenarios it might be required to update the whole local repository. In this case, you can run git pull
in the project root directory, but make sure to check the release notes for any breaking changes before doing
so.