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 .env file:

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

info

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.