{"id":20710712,"url":"https://github.com/debloper/piosk","last_synced_at":"2025-04-06T04:05:28.068Z","repository":{"id":245540940,"uuid":"816564221","full_name":"debloper/piosk","owner":"debloper","description":"One-shot set up Raspberry Pi in kiosk mode as a webpage shuffler, with a web interface for management.","archived":false,"fork":false,"pushed_at":"2025-02-23T07:59:11.000Z","size":317,"stargazers_count":134,"open_issues_count":27,"forks_count":14,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-04T20:47:28.628Z","etag":null,"topics":["digital-signage","kiosk-mode","raspberry-pi"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/debloper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"debloper"}},"created_at":"2024-06-18T02:09:22.000Z","updated_at":"2025-04-02T02:43:02.000Z","dependencies_parsed_at":"2024-07-12T03:45:42.067Z","dependency_job_id":"67679de5-4535-4e34-8aed-d5228e33f6d4","html_url":"https://github.com/debloper/piosk","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"4e3fd3ed3e9732a81b15c7259a571c17876ce657"},"previous_names":["debloper/piosk"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debloper%2Fpiosk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debloper%2Fpiosk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debloper%2Fpiosk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debloper%2Fpiosk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/debloper","download_url":"https://codeload.github.com/debloper/piosk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247430864,"owners_count":20937874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["digital-signage","kiosk-mode","raspberry-pi"],"created_at":"2024-11-17T02:12:56.444Z","updated_at":"2025-04-06T04:05:28.043Z","avatar_url":"https://github.com/debloper.png","language":"Shell","funding_links":["https://github.com/sponsors/debloper"],"categories":[],"sub_categories":[],"readme":"![PiOSK Banner](assets/banner.png)\n**One-shot set up Raspberry Pi in kiosk mode as a webpage shuffler, with a web interface for management.**\n\n# 0. Foreword\n\nThis started as a simple automation script \u0026mdash; a wrapper of the [official Raspberry Pi kiosk mode tutorial](https://www.raspberrypi.com/tutorials/how-to-use-a-raspberry-pi-in-kiosk-mode/) for personal use. Then one thing lead to the other and I found myself installing nodejs \u0026 writing systemd unit files...\n\nThat's when I realized... maybe there are other people (or future me) who'd also find this \"single script setup\" useful.\n\n\u003e [!NOTE]  \n\u003e And apparently, I wasn't wrong! From GitHub [stars](https://github.com/debloper/piosk/stargazers), [issue](https://github.com/debloper/piosk/issues) reports, to [news articles](https://www.hackster.io/news/fe890d007c32) covering PiOSK - the community acceptance has been far more than I had imagined. So, with the wide range of users, there's a need for stabilizing the repo and consolidating the features. The followup updates will be less frequent, and more thoroughly tested. It's not a feature freeze, but priority would be on the refactor and maintenance.\n\n\n# 1. Set Up Guide\n\n[![PiOSK Setup Video Walkthrough](https://img.youtube.com/vi/CrQjc6P-g1A/maxresdefault.jpg)](https://youtu.be/CrQjc6P-g1A)\n\n***PiOSK Setup Video Walkthrough***\n\n\u003e [!IMPORTANT]  \n\u003e PiOSK ***[assumes](#21-assumptions)*** a few things to keep itself lean and just focuses on the essentials. It should still work even if some of those assumptions aren't met, but it may require some tinkering \u0026 manual overrides. Issue reports or fixes for those edge cases are appreciated \u0026 welcome!\n\n\n## 1.1 Preparation\n\n0. Boot into Raspberry Pi desktop[^1]\n1. Ensure username, hostname etc. are configured\n2. Check ethernet/WiFi works \u0026 has internet access\n3. Enable [desktop auto login](https://www.raspberrypi.com/documentation/computers/configuration.html#boot-options) (set by default on RPi OS)\n\n[^1]: That is to say... boot into `runlevel 5` or `graphical.target` and not in console mode \u0026mdash; it's **NOT** a recommendation to use the 3.4GB boot image named [Raspberry Pi OS Desktop](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-desktop)\n\n\u003e [!NOTE]  \n\u003e Check [recommendations section](#22-recommendations) for more detailed explanations.\n\n\n## 1.2 Installation\n\nEither open terminal on the Raspberry Pi's desktop environment, or remote login to it; and run the following command:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/debloper/piosk/main/scripts/setup.sh | sudo bash -\n```\n\nThat's it[^2].\n\n[^2]: For some reason, if that's **NOT** it, and you hit a snag... please report an issue \u0026 give us some context to replicate \u0026 debug it.\n\n## 1.3 Configuration\n\n### 1.3.1 Basic\n\n1. Visit `http://\u003cpi's IP address\u003e/`[^3] from a different device on the network\n2. You should see the PiOSK dashboard with a list of sample URLs as kiosk mode screens\n3. Feel free to add \u0026 remove links as necessary (at least 1 link is necessary for it to work)\n4. The URLs don't have to be of remote domains. You can use localhost or even `file:///path`\n5. Once you're happy with the list, press `APPLY ⏻` button to apply changes and reboot PiOSK\n6. When rebooted, wait for the kiosk mode to start \u0026 flip through the pages in fullscreen mode\n\n\n### 1.3.2 Advanced\n\n\u003e [!WARNING]  \n\u003e Try these at your own risk; if you know what you're doing. Misconfiguration(s) may break the setup.\n\n1. The PiOSK repo is cloned to `/opt/piosk`\n2. You can change the dashboard port from `index.js`\n3. You can change the per-page timeout from `scripts/switcher.sh`\n4. You can change browser behavior (e.g. no full screen) from `scripts/runner.sh`\n5. Some changes can be applied without rebooting, but rebooting is simpler\n\n[^3]: PiOSK uses port 80 on the Pi to serve the web dashboard. If you're planning to use the Pi for other purposes, make sure to avoid port collision.\n\n![PiOSK Dashboard Web GUI](assets/dashboard.png)\n\n## 1.4 Updating\n\nFor now, there's no direct way to update the setup. This will change.\n\nYou 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.\n\nLook into the Uninstallation section for the next steps.\n\n\n## 1.5 Uninstallation\n\nIn order to uninstall/remove PiOSK from your system, run the `cleanup.sh` script:\n\n```bash\nsudo /opt/piosk/scripts/cleanup.sh\n```\n\n\u003e [!NOTE]  \n\u003e By default PiOSK doesn't uninstall the system packages it installs as dependencies (i.e. `git`, `jq`, `Node.js`, `wtype`). The reason being, if they're force removed, then other packages (which have been installed since) that may also rely on them - will break.\n\n# 2. Appendix\n\n## 2.1 Assumptions\n\n0. You're using a Raspberry Pi (other SBCs may work, not tested)\n1. You're using \"[Raspberry Pi OS with desktop (32bit)](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-32-bit)\" (other distros may work, not tested)\n2. You've applied proper [OS customizations](https://www.raspberrypi.com/documentation/computers/getting-started.html#advanced-options) \u0026 the Pi is able to access the internet (required for setup)\n3. You're not using port 80 on the Pi to run some other web server (apart from PiOSK dashboard)\n\n## 2.2 Recommendations\n\n- Choose the right device and OS\n  - If your Pi has 4GB or less memory, choose 32bit image\n  - Raspberry Pi Zeros struggle running Chromium due to low memory\n  - Raspberry Pi4 or Pi5 (or their compute modules) are ideal for PiOSK\n  - Apply the necessary customizations (user account, WiFi credentials, SSH access etc)\n- Choose the right display/screen\n  - Not related to PiOSK, but resolution matters for browser based kiosk mode\n    - Browser content window resolutions smaller than `1024px*600px` may not be ideal\n    - Different websites have different responsive rules \u0026 handle small screens differently\n  - Also be mindful of [LCD burn-in](https://en.wikipedia.org/wiki/Screen_burn-in) if displaying very limited number of static pages\n  - DSI displays are more discreet, but they may require driver setup to work properly\n- Take necessary steps to harden security\n    - Disable touchscreen unless required\n    - Disable ports that aren't required\n    - Disable unused network interfaces, remote SSH\n    - Enable OverlayFS to write protect storage\n- Discover the Pi on the network\n    - Set hostname (e.g. `piosk`) so you can call it by hostname without needing to hunt for IP\n    - The dashboard's URL with the hostname \u0026 IP address is shown at the end of the install script\n    - Or, run angry IP scanner or login to router/switch to discover the Pi's IP the hard way\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebloper%2Fpiosk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdebloper%2Fpiosk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebloper%2Fpiosk/lists"}