Waylight on a Raspberry Pi¶
The Raspberry Pi image turns a Pi into a small appliance for your start page:
flash an SD card, boot, open http://waylight.local. No Docker, no
terminal needed. It is Raspberry Pi OS Lite (64-bit) with Waylight
installed as a hardened service (ADR 0015);
everything runs on the Pi, your data never leaves it.
What you need¶
| Board | Raspberry Pi 5, 500, 4, 400, 3B/3B+ or Zero 2 W (64-bit). Pi 1, 2 and Zero W are not supported. |
| SD card | 8 GB or more, a reputable brand (A1/A2). |
| Power | The official power supply of your board — weak supplies cause most "random" problems. |
| Network | Ethernet, or Wi-Fi configured while flashing. |
1. Flash the SD card¶
Install Raspberry Pi Imager (version 2.0 or newer).
Recommended — Imager knows the image and offers its customisation:
- App Options → Content Repository → Use custom URL, enter
https://github.com/itadori26/waylight/releases/latest/download/os_list.json - Choose your device, then Waylight as operating system, then the SD card.
- In the customisation step set at least a user and password, and Wi-Fi if the Pi has no cable. Hostname, time zone and SSH are optional. Write.
Alternative — "Use custom" with the downloaded file: download
waylight-<version>-raspberrypi-arm64.img.xz from the
latest release,
check it against the .sha256 file and write it with Use custom. Imager may
not offer its customisation for a local file, so use Ethernet and add a user
later on the console if you need one. Waylight itself needs no user
account on the Pi.
To check that the image was built by this repository's release workflow and not changed since (#138), verify its signed build provenance with the GitHub CLI:
gh attestation verify waylight-<version>-raspberrypi-arm64.img.xz -R itadori26/waylight
The release also carries the image's SPDX SBOM
(waylight-<version>-raspberrypi-arm64.spdx.json).
2. First start and setup¶
Insert the card, connect the network and power. The first boot takes one to three minutes (the file system is enlarged, keys are generated). Then open
http://waylight.local— orhttp://<your-hostname>.localif you set a hostname in Imager,- or the Pi's IP address, which your router lists (e.g. FRITZ!Box: Home
Network → Network). Some Android phones and older Windows versions do not
resolve
.localnames.
The setup page asks for the setup token. It is created on the Pi during the first boot, is different on every device, and works only until your account exists. You find it
- on a monitor attached to the Pi, above the login prompt,
- in
waylight-setup.txton the SD card — shut the Pi down, put the card into any computer and open the file on the smallbootfsdrive, - with
sudo waylight-setup-tokenover SSH.
Choose a password (at least 12 characters) — done. The setup copies of the token are deleted automatically afterwards. Want to choose the token yourself? See Setup token in the native install guide.
Updates¶
The Pi installs updates by itself every night: security updates of Raspberry Pi OS, kernel and firmware, and new Waylight releases. If an update needs a reboot (e.g. a new kernel), it reboots at 04:00. Settings → About shows the running version.
Before every Waylight update the database is copied to
/var/lib/waylight/backups/pre-upgrade/.
- Hold a version:
sudo apt-mark hold waylight(unholdto continue). - Roll back:
sudo apt install --allow-downgrades waylight=<version>(the last five releases are available).
Backups¶
Waylight creates a database backup every day and keeps seven; download them under Settings → Backups. Keep the key as well — without it stored integration passwords (CalDAV, AdGuard Home, …) cannot be decrypted:
sudo cat /etc/waylight/secret.env
For a copy outside the SD card, put the backups on a USB stick (see Sandbox in the native install guide) or use Settings → Export.
Restore on a new SD card: flash the image, do not finish the setup, then
over SSH: sudo systemctl stop waylight, copy your backup to
/var/lib/waylight/waylight.db and your old SECRET_KEY into
/etc/waylight/waylight.env, run
sudo chown waylight:waylight /var/lib/waylight/waylight.db and
sudo systemctl start waylight.
HTTPS and passkeys¶
On the local network plain http:// works. For access from outside use a VPN
(WireGuard, Tailscale) rather than forwarding a port. HTTPS — needed for
passkeys and to install Waylight as an app — works with a reverse proxy
(guide); set PUBLIC_URL and COOKIE_SECURE=true in
/etc/waylight/waylight.env.
Configuration¶
Everything you would set in Docker's .env goes into
/etc/waylight/waylight.env; values there override the image defaults
(port 80, see /etc/waylight/appliance.env). Apply with
sudo systemctl restart waylight.
Moving between the Pi and Docker¶
Settings → Export creates a JSON file with all your data (never secrets);
Settings → Import reads it on the other installation. To move everything
including history, copy the database and SECRET_KEY as described in
Moving from Docker in the native install guide.
Tested so far¶
The image and the display mode are built and checked in CI, but have not yet been measured on real hardware: idle memory and CPU on a Pi Zero 2 W and a Pi 4, and the kiosk display on a Pi 4/5 with HDMI and the official touch display. If you run Waylight on a Pi, a short report in #361 helps; the numbers will be added here.
Troubleshooting¶
| Problem | What to do |
|---|---|
waylight.local does not open |
Use the IP address from your router. Wait three minutes after the first boot. Check that phone or laptop are in the same network (not a guest Wi-Fi). |
| No network over Wi-Fi | Wi-Fi is only set when flashing with Imager's customisation; flash again or use a cable. |
| The Pi does not boot (no green LED activity) | Flash the card again, try another card and the official power supply. |
| Forgot the password | sudo -u waylight sh -c 'set -a; . /etc/waylight/secret.env; . /etc/waylight/appliance.env; . /etc/waylight/waylight.env; exec waylight reset-account', then sudo systemctl restart waylight and sudo waylight-setup-token. |
| Something does not work | systemctl status waylight and journalctl -u waylight -n 100. The journal is limited to 50 MB to spare the SD card. |
| SD card full | df -h /; old backups are deleted automatically (BACKUP_RETENTION). |