Setup guide
The whole process, start to finish. Budget about 20 minutes, most of it spent waiting on downloads.
Download and open Raspberry Pi Imager — the official, free tool from Raspberry Pi themselves. Insert your SD card, then in Imager:
Choose OS → Raspberry Pi OS (64-bit). Choose Storage → your SD card.
Before clicking "Next," click the gear/settings icon (or you'll be prompted) to pre-configure things — set a hostname, enable SSH, and enter your Wi-Fi details here. Doing this now means the Pi connects to your network automatically on first boot, without needing a keyboard/mouse plugged into it at all.
Click Write, and wait for it to finish (this is the slow part).
Move the SD card to the Pi, connect it to your screen, and power it on. Give it a couple of minutes for its first boot — it's doing some one-time setup in the background.
If you're on the Pi directly, open a Terminal window. If you're connecting from another computer instead, open your own terminal and connect over SSH first (replace with the hostname you set in step 1):
Then run the installer:
This downloads the latest version and sets everything up automatically — Node.js, the app itself, and the wall-display kiosk mode. It'll ask for your password partway through (for a couple of one-time system installs) and reboot automatically when it's done.
After it reboots, the calendar display should appear automatically on the connected screen. From your phone or any browser on the same network, visit the address shown on that screen to finish setup — you'll pick whether this is your main device, and (for the main device) enter an email to activate it. If you use Home Assistant, setup will also ask if you'd like to connect it — optional, and just as easy to do later from Settings if you'd rather skip it for now. No payment required — the email is just how you get update notices.
From there: themes, calendar sources, and everyone in your family or team.
One shortcut worth knowing: Ctrl+Alt+K toggles the kiosk display on or off, if you ever need to get to a terminal on the Pi itself.
Depends which part. If ~/piazzahq doesn't exist yet, the one-line install command is safe to run again from scratch. If it already exists (even from a partial/failed attempt), don't re-run the one-liner — it'll refuse on purpose, to avoid wiping anything. Instead run bash ~/piazzahq/install.sh directly; that part is genuinely safe to re-run as many times as needed, and won't repeat steps that already succeeded. If it keeps failing at the same point, note the exact error and reach out.
Give it another minute — the kiosk display can take a moment to start after boot. If it's still blank, check the HDMI cable is in the port labeled HDMI0 on a Pi 4/5, not the second port.
It's shown directly on the wall display itself once it's running. If you set a custom hostname in step 1, try http://<that-hostname>.local from a phone on the same Wi-Fi network.
Yes — any device with a web browser can be a screen: an old tablet, a Fire Stick or Chromecast's built-in browser, a spare monitor on a cheap streaming box. In the app, go to Devices → "Add a Display," pick which layout it should show, and either scan the QR code on the new device or type in the address shown. It'll show up in your Screens list the first time it loads.
If the new device is on the same Wi-Fi as your Pi, this works immediately. For something that moves between networks — a tablet you carry room to room, say — install Tailscale on both the Pi and the new device first; the app detects it automatically and gives you a link that works from anywhere on your tailnet instead of just the current Wi-Fi.
Home Assistant is a separate, free project — it doesn't come with Piazza HQ, and setup here only handles connecting to one you already have running. If you're starting from scratch, the easiest hands-off option is Home Assistant Green — a small box that arrives with it already installed, just add power and network.
If you'd rather run it yourself on hardware you already have (a spare Pi, or the same machine as your Piazza HQ central server), this is the official Docker install command — works on a Raspberry Pi or any Linux box with Docker Engine already installed (swap in your own timezone and a folder for its config first):
Once it's running, visit http://<that machine's address>:8123 to finish its own setup — then come back here (Settings → Home Assistant, or the setup wizard on a fresh install) to connect it.
This Docker path doesn't include Home Assistant's optional "apps" (Zigbee2MQTT, an MQTT broker, etc.) — fine for connecting sensors and switches to Piazza HQ, but if you think you'll want those, flashing the full Home Assistant OS instead gets you those too. Home Assistant's own install process can change over time — their official installation docs are the source of truth if anything here looks out of date.
Setup asks if you want to during first-run — just paste your Home Assistant URL (e.g. http://homeassistant.local:8123) and a Long-Lived Access Token (in Home Assistant: your profile → Security tab → Long-Lived Access Tokens → Create Token). Skipped it, or setting up a second display? Do it anytime from Settings → Home Assistant instead. Either way, the URL and token stay on your own server — they're never sent to the display or anyone's phone. Once connected, add an Entity Status widget from Layout to show any sensor or device's current state, toggle lights and switches, adjust a thermostat, or run a scene.
Download PiazzaHQ-Setup.exe and run it. No admin rights needed — it installs to your own user folder (%LocalAppData%\PiazzaHQ), not Program Files, so there's no UAC prompt.
Node.js is bundled in — nothing else to install separately.
One checkbox on the "Select Additional Tasks" page of the wizard:
Left unchecked (default) — control device. A normal Desktop shortcut opens the app windowed, in your regular browser. Good for the PC you'll actually use day to day.
Checked — wall display. Every shortcut opens the calendar full-screen with no browser chrome, and it's added to Startup so it comes up automatically the next time you sign in. Use this on a PC that's dedicated to being the display.
Check "Launch now" at the end of setup, or just double-click the new Desktop shortcut. First run, Windows Firewall will ask to allow the app on your network — say yes; this is normal for anything that opens a listening port, unrelated to signing.
Wall-display mode: give it a few seconds, then it fills the screen. To get out of the full screen, tap/click anywhere on it once — a small ⤢ Exit full-screen button appears in the corner for a few seconds (Alt+F4 always works too).
Same as everywhere else from here: from your phone or any browser on the same network, visit the address shown on the display to finish setup — pick whether this is your main device, and enter an email to activate it. Themes, calendar sources, everyone in your family or team, all the same as the Pi.
Updates arrive the same way too — the app checks in and self-updates automatically. You only need to re-run the installer again for something that touches the installer itself (rare — we'll always say so explicitly if a release needs it).
Click More info on the blue warning screen, then Run anyway. This build is deliberately unsigned for now — the warning is expected, not a sign anything's actually wrong with the file.
Tap or click anywhere on the screen — a small ⤢ Exit full-screen button appears in the corner. Alt+F4 always works too. (The tap-to-reveal button needs an installer from this guide's current build; a much older install may only have Alt+F4 until it's reinstalled.)
Yes — same as the Pi: any device with a browser can be a screen. In the app, go to Devices → "Add a Display," pick a layout, and scan the QR code or type in the address shown from the new device.
Already running other self-hosted apps (Plex, Home Assistant, a NAS's app store) on this machine? You almost certainly have it. If not, the official install is one line on Linux:
On Mac or Windows, install Docker Desktop instead.
Create a folder for it, and inside, a file named docker-compose.yml with this:
Swap in your own timezone. That's the whole config — your data lives in the named volume, safely separate from the container itself.
That's it — no separate install script, no OS packages to manage beyond Docker itself.
Visit http://<that machine's address>:3000/app from your phone or any browser on the same network to finish setup — pick whether this is your main device, and enter an email to activate it. Everything else (themes, calendar sources, everyone in your family or team) works exactly the same as the Pi — you're just managing it entirely from a browser instead of a physical screen.
Updates work differently here on purpose: the in-app updater is disabled in a container (there's nowhere for it to write to). Instead:
Bridge networking (the default in the compose file above) is fine for calendar feeds, weather, and updates, but can't discover LAN devices or resolve .local hostnames. Drop the ports: block and add network_mode: host instead — the app then runs directly on the host's own network.
In the piazzahq-data named Docker volume, not inside the container — pulling a new image and recreating the container never touches it. Find its real path on disk with docker volume inspect piazzahq-data if you want to back it up directly, or use Settings → Backups → "Download full backup" from inside the app.
Yes — same as everywhere else: any device with a browser can be a screen. In the app, go to Devices → "Add a Display," pick a layout, and scan the QR code or type in the address shown from the new device.
Yes — Proxmox itself isn't a Docker host, so it runs inside either a VM or an LXC container on your Proxmox server, but either way it's the exact same setup from there. Simplest: a small Debian or Ubuntu VM (1 vCPU, ~1GB RAM is plenty) with Docker installed the normal way, then follow this guide as-is. Prefer an LXC container instead? Enable Nesting and Keyctl under that container's Options → Features first — Docker needs those to create its own nested namespaces — then install Docker inside it the same way.
Setting up remote access, switching to X11 manually, checking logs — see the troubleshooting page for copy-paste commands (Pi-specific for now).
Ready to explore what's actually in the app? The user guide covers every tab.