One-shot set up Raspberry Pi in kiosk mode as a webpage shuffler, with a web interface for management.

This started as a simple automation script — a wrapper of the official Raspberry Pi kiosk mode tutorial for personal use. Then one thing lead to the other and I found myself installing nodejs & writing systemd unit files...

That's when I realized... maybe there are other people (or future me) who'd also find it useful.

This is far from done. It's just the first checkpoint that meets my initial goal of making the entire process a "single script setup".

PiOSK Setup Video Walkthrough

1. Boot into Raspberry Pi desktop¹
2. Ensure network/WiFi/internet is working
3. Ensure desktop auto login is enabled (is default)
4. Ensure screen does not timeout & adjust brightness
5. Ensure SSH is working if you want to install remotely

Either open terminal on the Raspberry Pi's desktop environment, or remote login to it; and run the following command:

curl -sSL https://raw.githubusercontent.com/debloper/piosk/main/setup.sh | sudo bash -

That's it².

1. Visit http:https://<pi's IP address>/³ from a different device on the network
2. You should see the PiOSK dashboard with a list of sample URLs as kiosk mode screens
3. Feel free to add & remove links as necessary (at least 1 link is necessary for it to work)
4. Once you're happy with the list, press APPLY ⏻ button to apply changes and reboot PiOSK
5. When rebooted, wait for the kiosk mode to start & flip through the pages in fullscreen mode

1. The PiOSK repo is cloned to the user's $HOME/piosk
2. You can change the dashboard port from index.js
3. You can change the per-page timeout from switcher.sh
4. You can change browser behavior (e.g. no full screen) from browser.sh
5. Some changes can be applied without rebooting, but rebooting is safer

For now, there's no direct way to update the setup. This will change.

You should uninstall old version and then reinstall the new version. As long as you don't delete the backup config file (created during uninstallation), it should be picked up and reinstated by the reinstallation process.

Look into the Uninstallation section for the next steps.

In order to uninstall/remove PiOSK from your system, run the cleanup.sh script as the user for whom PiOSK was installed:

sudo cleanup.sh

1. You're using a Raspberry Pi (other SBCs may work, not tested)
2. You're using "Raspberry Pi OS with desktop (32bit)" (other distros may work, not tested)
3. You've applied proper OS customizations & the Pi is able to access the internet (required for setup)
4. You're using Wayland with Wayfire compositor (probably the only "must have" during runtime)
5. You're using the same user to run the setup script for whom desktop auto login is configured
6. You're not using port 80 on the Pi to run some other web server (apart from PiOSK dashboard)

• Choose the right Raspberry Pi
  • Pi Zero 2 W is perhaps the most fitting RPi for the job
  • Older Pi Zero (1.3, Zero W etc.) may struggle running Chromium
  • A Pi4 or Pi5 may be overkill, but shouldn't face any issue
• Choose the right display/screen
  • Not related to PiOSK, but resolution matters for browser based kiosk mode
    • Browser content window resolutions smaller than 1024px*600px may not be ideal
    • Different websites have different responsive rules & handle small screens differently
  • Also be mindful of LCD burn-in if displaying very limited number of static pages
  • DSI displays are more discreet, but they may require driver setup to work properly
• Choose the right OS Image
  • Use the Pi imager tool for flashing
  • If your Pi has 4GB or less memory, choose 32bit image
  • Use Debian Bookworm based images (for better Wayland/Wayfire support)
• Take necessary steps to harden security
  • Disable touchscreen unless required
  • Disable ports that aren't required
  • Disable unused network interfaces, remote SSH
  • Enable OverlayFS to write protect storage
• Discover the Pi on the network
  • Set hostname (e.g. piosk) so you can call it by hostname without needing to hunt for IP
  • The dashboard's URL with the hostname & IP address is shown at the end of the install script
  • Or, run angry IP scanner or login to router/switch to discover the Pi's IP the hard way