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.yml. After startup, open http://yourServerIpAddress or https://yourTailscaleDomain