Native install (Debian, Ubuntu, Raspberry Pi OS)¶
Waylight is a single static binary, so it does not need Docker. Every
release attaches .deb packages for amd64 and arm64 that install it as a
hardened systemd service. This is also what the Raspberry Pi image is built
from (ADR 0015).
Docker stays the primary setup on a server that already runs containers; the native package is for machines without Docker and for small single-purpose devices.
Install¶
Pick the package for your architecture (dpkg --print-architecture) from the
latest release,
check it and install it:
VERSION=1.2.3 # the release you want
ARCH=$(dpkg --print-architecture)
curl -fLO "https://github.com/itadori26/waylight/releases/download/v$VERSION/waylight_${VERSION}_$ARCH.deb"
curl -fLO "https://github.com/itadori26/waylight/releases/download/v$VERSION/waylight_${VERSION}_packages.sha256"
sha256sum --check --ignore-missing "waylight_${VERSION}_packages.sha256"
sudo apt install "./waylight_${VERSION}_$ARCH.deb"
The service starts right away on port 8090. Show the address and the one-time setup token, open the address and enter the token:
sudo waylight-setup-token
Setup token¶
Like SECRET_KEY, the setup token is generated on the device on the first
start (20 characters without look-alikes, e.g. K7MP-Q2XA-9HTD-WE4R-ZN6C) and
is only valid until the account exists. Ways to get it — all of them need
access to the device itself:
sudo waylight-setup-tokenover SSH or on the console- on a monitor attached to the device, above the login prompt
- on a Raspberry Pi:
waylight-setup.txton the boot partition of the SD card (readable on any computer) - in the log:
sudo journalctl -u waylight | grep setup_token
Console text and boot partition file are deleted automatically once the
account exists (waylight-setup-info.timer). To choose the token yourself
(automated setups), set SETUP_TOKEN= (at least 16 characters) in
waylight.env.
What the package installs¶
| Path | Purpose |
|---|---|
/usr/bin/waylight |
The binary (same as in the container image) |
/etc/waylight/waylight.env |
Configuration (environment variables, see .env.example) |
/etc/waylight/secret.env |
SECRET_KEY and SETUP_TOKEN, generated on the first start |
/var/lib/waylight/ |
Database and automatic backups |
waylight.service |
systemd unit, runs as the system user waylight |
SECRET_KEY is created on the device on the first start (32 random bytes)
— it is never part of a package or an image. It encrypts stored integration
passwords: keep a copy of /etc/waylight/secret.env with your backups.
After changing the configuration: sudo systemctl restart waylight.
Defaults differ from Docker where Docker needed workarounds: host metrics are
read from /proc and /sys directly, Wake-on-LAN broadcasts without a relay,
and the Docker module is disabled (MODULES_DISABLED=docker) because there is
no Docker socket proxy.
Sandbox¶
The service runs without capabilities and with a read-only view of the
system; only /var/lib/waylight is writable. Check it with
systemd-analyze security waylight (CI keeps the exposure at or below
2.0). Changes go into a drop-in (sudo systemctl edit waylight), never
into the packaged unit:
# Listen on port 80 (also set LISTEN_ADDR=:80 in waylight.env)
[Service]
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
# Backups on a USB stick (also set BACKUP_DIR=/mnt/usb/waylight in waylight.env)
[Service]
ReadWritePaths=/mnt/usb/waylight
Robustness¶
- Watchdog: the service reports readiness to systemd and pings its
watchdog every 30 seconds while the database answers. If it hangs, systemd
restarts it after 60 seconds (
WatchdogSec=). - Power loss: SQLite runs in WAL mode with
synchronous=NORMAL. After a sudden power cut the database is always consistent; at worst the last change before the cut is lost. Daily backups cover the rest.
Update and rollback¶
With the APT repository (recommended; the Raspberry Pi image is set up this way and updates itself every night):
sudo curl -fsSLo /usr/share/keyrings/waylight-archive-keyring.asc \
https://itadori26.github.io/waylight/apt/waylight-archive-keyring.asc
sudo tee /etc/apt/sources.list.d/waylight.sources >/dev/null <<'EOF'
Types: deb
URIs: https://itadori26.github.io/waylight/apt
Suites: stable
Components: main
Signed-By: /usr/share/keyrings/waylight-archive-keyring.asc
EOF
sudo apt update && sudo apt install waylight
Afterwards sudo apt upgrade updates Waylight like every other package,
and unattended-upgrades can do it automatically (add
"origin=waylight,codename=stable"; to Unattended-Upgrade::Origins-Pattern).
Check the key's fingerprint against the one in the release notes before
trusting it.
Without the repository, install the newer .deb the same way as the
first one.
Either way configuration, key and data are kept, the service restarts, and
before every upgrade the database is copied to
/var/lib/waylight/backups/pre-upgrade/ (the three newest copies stay).
Rollback: the repository keeps the last five versions.
sudo apt install --allow-downgrades waylight=1.2.3
Database migrations only add columns and tables, so an older version runs on
newer data. To return to the exact data of before the upgrade:
sudo systemctl stop waylight, delete waylight.db-wal and
waylight.db-shm in /var/lib/waylight, copy the matching
backups/pre-upgrade/waylight-<version>-<time>.db to waylight.db
(and its -wal file, if there is one, to waylight.db-wal), then start
the service again.
Forgot the password?¶
sudo -u waylight sh -c 'set -a; . /etc/waylight/secret.env; . /etc/waylight/waylight.env; exec waylight reset-account'
sudo systemctl restart waylight
sudo waylight-setup-token
Moving from Docker¶
- Stop the container and copy the database out of the volume (see
backups) to
/var/lib/waylight/waylight.db. - Put your existing
SECRET_KEYinto/etc/waylight/waylight.env— a key there always wins over the generated one. sudo chown -R waylight:waylight /var/lib/waylightandsudo systemctl restart waylight.
Uninstall¶
sudo apt remove waylightstops the service and keeps configuration and data.sudo apt purge waylightalso deletes/etc/waylight. The data in/var/lib/waylightis never deleted automatically; the generated key is moved next to it (secret.env.purged) so a reinstall can still decrypt it. Delete the directory yourself if you no longer need it.