Making a Kiosk

The Browser:

After toiling with numerous chrome and Firefox extensions, as well as Microsoft Window's Kiosk mode, I came to the sinking realization that I was going to have to develop my own in-house solution. Fortunately, with a little python skills (and a lot of chatGPT), I was able to develop my own Kiosk browser using PyQt5. I won't bore you with the details, but suffice to say you can download my work, or dig into my code over at gitlab. The browser itself should work on most versions of Linux, including some later models of the raspberry pi, but also Windows and Mac.

Note, this app won't stop users from closing the browser and starting other applications, this is where Gnome Kiosk comes into play, and why this tutorial focuses only on Linux.

The Kiosk Environment

I used Gnome Kiosk to deploy a kiosk experience. Per their Github repository:

"GNOME Kiosk provides a desktop environment suitable for fixed purpose, or single application deployments like wall displays and point-of-sale systems.

It provides a very minimal wayland display server and compositor and Xorg compositor and window manager. It automatically starts applications fullscreen.

Notably, GNOME Kiosk features no panels, dashes, or docks that could distract from the application using it as a platform."

NOTE: As of this writing Gnome Kiosk is still in early development and isn't available to install on many Linux repositories. I had the most success using Ubuntu 24.04, although it is also available on Fedora based systems. Speaking of Fedora, my project was largely inspired by this blog post by Fedora Magazine. My preference for Ubuntu related to an auto logon issue, but I'll spare you the details. I had success on x64 machines; the Raspberry pi was a bit of a fail. Your millage may vary.

Knowledge Assumptions: You should be comfortable installing Linux based systems and be somewhat familiar with the terminal.

Instructions:

Step 1: Download and Install Ubuntu Desktop. While going through the install prompts create a user called kiosk.

Step 2: Run the software updater program to ensure your running the latest software and utilities on Ubuntu. You can also do this in the terminal"

      sudo apt update && sudo apt upgrade
    

Step 3: Create an additional user called Administrator. You can do this by hitting super key --> Type settings --> System --> Users. Make sure the Administrator toggle is turned on. This account serve as a fallback to make changes after we've fully configured the kiosk and removed the admin rights for the kiosk user.

Step 4: Install gnome kiosk. Open the terminal and type the following to install gnome kiosk.

      sudo apt install gnome-kiosk
    

We'll start off by creating a gnome kiosk script that we'll edit later to auto start the browser. Enter the following in the terminal:

      gnome-kiosk-script
    

A configuration file will appear on screen. This file is located in ~/.local/bin/gnome-kiosk-script. (or /home/kiosk/.local/bin/gnome-kiosk-script). You can close the file by typing ctrl + x, and ten y to save. We'll edit this configuration file shortly.

Installing PyQt5 and Downloading the Kiosk Browser Code From Gitlab

The code snippet below will install python3 pip, git, and pyqt5, including the web engine, the necessary dependencies to run the kiosk browser.

      sudo apt install python3-pip && sudo apt install git && sudo apt install python3-pyqt5 && sudo apt install python3-pyqt5.qtwebengine
    

Download the kiosk browser code from gitlab:

      git clone https://gitlab.com/pentictonlibrary/kiosk-browser
    

Inside the folder you'll see a file called kiosk-webpage.txt. Replace the duckduckgo.com search engine with the webpage of your choice (or just leave it at duckduckgo.com, your choice).

      cd kiosk-browser
    

      python3 kiosk-browser.py
    

When you're finished you can close your terminal window to exit

Note (TLDR): python programmers will tell you that you should run your projects in isolated python virtual environments. While I agree with them, I'd preferring to keep this tutorial as simple as I can make it, and truth be told, your kiosk should run absolutely fine without completing these steps. If you're really curious, you can check out the gitlab page where I describe getting how to run the kiosk in a python virtual environment. I should also mention that as of this writing PyQt5 will not install properly on a raspberry pi using the virtual environment with the pip package.

Setting the Kiosk Browser to Load on Boot

When the gnome kiosk desktop environment launches, we'll need the kiosk browser to load. This is done by editing the gnome-kiosk configuration file we created earlier. In the terminal enter the following command:

      nano /.local/bin/gnome-kiosk-script
    

put a # in front of the line gnome-text-editor ~/.local/bin/gnome-kiosk-script (or just delete it). Then add the following lines:

cd ~/kiosk-browser && python3 kiosk-browser.py

If you've done it correctly, it will look like the image below:

Getting Into Kiosk Mode:

To start gnome kiosk, log out of your session. Now at the login screen, select the gear icon on the lower right. Select Gnome Kiosk Script (Wayland Display Server). Login with your kiosk username and password and the browser should load. (side note, X11 is quickly reaching end-of-life and should be avoided whenever possible)

If you've set everything up correctly, the kiosk should be running!

Exiting The Kiosk Environment

To get out of kiosk mode enter Ctrl + Alt + F3. You'll be launched into a full screen terminal. Login with your username and password. Type reboot and hit enter. After your PC reboots you can switch the display back to Ubuntu, or log in as the Administrator account. Admittedly, it's annoying to have to reboot, but I haven't figured out a better alternative.

Recommended Settings

On the kiosk account you'll want to set a few things before launching it to your users. In settings, adjust the power settings to your liking, and set blank screen to never. Open the software and Updates app and adjust the update schedule to your liking. I'd recommend setting the updates to install automatically.

Securing Accounts and Automatic Login

Let's remove the administrative rights from our kiosk user. To do this, log out of the kiosk account, and login in with the administrator. In Settings --> system users. On the kiosk user, toggle off administrator. We'll also toggle on automatic login, so our kiosks loads at boot.

Last Steps

1) Log out of the Administrator Account

2) At the Login Screen, select the kiosk user, and re-enable Gnome Kiosk (Wayland Server).

3) Log in with your username and password and you're good to go!

Turning Off Kiosk Mode after Auto Logon has been enabled

If you've made a mistake, or wish to make any changes, you'll need to re-enable the default desktop environment by using the command line. Hit Ctrl + alt + F3 to load the terminal. Then enter:

      su Administrator
    

(enter the admin password)

      sudo nano /var/lib/AccountsService/users/kiosk
    

Enter the following command to edit the default session of the kiosk account:

put a # in front of the Session=gnome-kiosk-script-wayland to comment it out. Write the following

      Session=Ubuntu
    

Save the file (control x) and type sudo reboot to restart.

The kiosk user will now automatically boot into an Ubuntu gnome session. From here you can go into the settings to turn automatic login off, or really change anything else you'd like.

Bonus: Set the Kiosks to Shutdown at closing time

To set Ubuntu to shutdown at specific times of the day you can use cron. There is plenty of documentation on cron so I'll just leave this snippet below to shutdown the kiosk at 6pm Monday through Friday.

using the administrator account enter the following:

      sudo crontab -e
    

(If you're asked which editor to use, select 1 for nano)

Enter the following at the bottom of the file:

      0 18 * * 1-5 /sbin/shutdown -h now
    

OK it only took 5 months but I finally finished my second blog post. This one was a bit of a doozy. If you've made it to the end, congratulations! And thank you!