Troubleshooting — Piazza HQ

Add remote access

Reach the control app from anywhere, not just your home network — sets up Tailscale, a private network (nothing exposed publicly). This is interactive: it'll show you a login link to open once in any browser.

bash ~/piazzahq/setup-remote-access.sh

Already set up? Check its status:

bash ~/piazzahq/setup-remote-access.sh --status

Once this is set up, you can also SSH in from your phone — an app like Termius or PiSSH works well — using the same address Tailscale gives the Pi, no different from SSHing in from a computer.

Switch to X11

The installer offers this automatically near the end of setup. If you skipped it, or want to do it manually:

sudo raspi-config nonint do_wayland W1 && sudo reboot

If that doesn't work on your image, do it through the menu instead: sudo raspi-config → 6 Advanced Options → Wayland → W1 X11 → reboot.

Setup didn't finish, or something went wrong

Safe to run again as many times as needed — it won't repeat steps that already succeeded, and never touches your actual data (events, photos, chores).

bash ~/piazzahq/install.sh

Don't re-run the one-line curl | bash install command once ~/piazzahq already exists — it refuses on purpose, specifically so it can't be used to accidentally wipe a real install. The command above is the one that's actually safe to repeat.

Wipe everything and start completely fresh

Destructive. This is a different, much bigger step than the repair command above — use it only if you genuinely want to lose everything and set up as if this were a brand new Pi. The vast majority of "something's wrong" situations are the repair command above, not this.

curl -sSL https://piazzahq.com/fresh-install | bash

Makes a local backup of your database and photos before deleting anything, and requires typing a full confirmation phrase (not just yes/no) before it touches anything — but a backup you haven't verified isn't a backup you can rely on. Deletes every event, photo, layout, setting, and your PIN, then reinstalls from scratch.

Remove Piazza HQ from this device entirely

Destructive. Different from the fresh-install command above — this doesn't reinstall anything afterward. Use this when you actually want Piazza HQ gone from this specific device (retiring it, repurposing the Pi for something else), not when you're troubleshooting.

curl -sSL https://piazzahq.com/uninstall | bash

Same local backup-first behavior and typed confirmation as the fresh-install command above. Stops and disables the service, removes the systemd service file, and deletes the whole install folder (database, photos, every setting) — then stops, with nothing reinstalled. To set the device back up later, use the normal install command.

Kiosk display controls

Drop in and out of the fullscreen display without racing an auto-relaunching browser.

Current installs bind Ctrl+Alt+K automatically to kiosk toggle — no SSH needed for routine use. (Older installs may still have the previous Super+K binding, which turned out to conflict with the Raspberry Pi desktop's own "tap Super to open the menu" gesture — re-running install.sh adds Ctrl+Alt+K alongside it without removing the old one.) The commands below stop the underlying process cleanly either way, and are the only option if you're on a device with no keyboard at all. If you're physically at the Pi with no SSH access and need a terminal, Ctrl+Alt+F2 switches to a text console below the whole graphical session — log in there and run kiosk off.

kiosk off

Bring it back:

kiosk on

Or just flip between the two:

kiosk toggle

Check whether the app is actually running

sudo systemctl status piazzahq

Watch its logs live (useful if something's actually broken):

journalctl -u piazzahq -f

Restart it (e.g. after manually changing a setting):

sudo systemctl restart piazzahq

Still stuck? Get in touch — include what you ran and what actually happened, and it's usually a quick fix.