Installation

Zonal is a three-part system. Install each component on the appropriate machine and they will discover each other over your local network using MQTT.

Components

Component	Runs on	Purpose
Controller	Any always-on server or PC	MQTT broker, API, license enforcement
Dashboard	Browser (any device)	Real-time monitoring UI
Monitor agent	Raspberry Pi at each zone	Captures SPL, reports over MQTT

Controller — Windows

Download the Windows installer (v3.12.0) from the customer portal.
Run the installer as Administrator. It installs the Zonal service and starts it automatically.
Open Services (services.msc) and confirm Zonal Controller is running.
Navigate to http://localhost:4000 in a browser — you should see the dashboard login page.
Activate your license from the License panel using the key from your confirmation email.

Controller — Linux

DEB (Debian / Ubuntu)

# Download from your portal or run:
wget "https://github.com/SteepleStack/zonal/releases/download/v3.12.0/steeplestack-zonal-controller_3.12.0_amd64.deb"
sudo dpkg -i steeplestack-zonal-controller_3.12.0_amd64.deb
sudo systemctl enable --now zonal-controller

Generic binary

# Download from your portal or run:
wget "https://github.com/SteepleStack/zonal/releases/download/v3.12.0/Steeplestack-Zonal-Controller-linux" -O zonal-controller
chmod +x zonal-controller
./zonal-controller

Controller — Docker

See the dedicated Docker guide for a full docker-compose.yml example.

docker run -d \
  -e SPL_LICENSE_KEY=SPL-XXXX-XXXX-XXXX-XXXX \
  -p 4000:4000 \
  --name zonal \
  ghcr.io/steeplestack/zonal:latest

Monitor agent (Raspberry Pi)

Flash a Raspberry Pi with Raspberry Pi OS Lite (64-bit recommended) and enable SSH.
SSH in and run the one-line provisioning script shown in the dashboard under Monitors → Add monitor.
The script installs the agent, sets the controller address, and starts the service. The monitor appears in the dashboard within seconds.

curl -fsSL https://steeplestack.org/provision | sudo bash -s -- \
  --controller YOUR_CONTROLLER_IP \
  --name "Sanctuary Left"

Verifying the install

Open the dashboard and navigate to Monitors. Each online monitor shows a live SPL reading. If a monitor is offline, check:

Both devices are on the same network (or MQTT port 1883 is reachable).
The controller's firewall allows inbound connections on port 4000 (dashboard) and 1883 (MQTT).
The monitor service is running: sudo systemctl status zonal-monitor

Upgrading

The controller checks for updates on startup and displays a banner in the dashboard when a new version is available. Download the new installer from the customer portal and run it over the existing installation — your configuration and license are preserved.