Skip to content

Instantly share code, notes, and snippets.

@anjohnson
Last active June 2, 2023 14:16
Show Gist options
  • Star 3 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save anjohnson/a86e967e44cb01cf2d61 to your computer and use it in GitHub Desktop.
Save anjohnson/a86e967e44cb01cf2d61 to your computer and use it in GitHub Desktop.
How to set up a PC as an unattended Kiosk running a closed website

How to set up a PC as an unattended Kiosk running a closed website, using Ubuntu 14.04.02 LTS.

These instructions assume that you're familiar with Linux and system administration.

You will need an internet connection to set up the kiosk, even if all the pages will be loaded from disk when it's running.

Note that a "closed" website is one with no links to other websites or to pages with no links back to the rest of the site. The idea here is to only allow users to access a limited set of pages since the kiosk is provided for a specific purpose. If you develop your own content for the kiosk to display, make sure that all pages have at least one link back to the rest of the site; the Back button isn't displayed by Chromium when in kiosk mode.

Users of the Volgistics "VicTouch" software may find these instructions useful.

Install Linux

First install Ubuntu 14.04.02 LTS Server by downloading the server .iso image and copying it to either a cdrom or a flash stick and booting from it. When the Ubuntu installer asks for login account details, give those for the administrator's account, not the kiosk account. If this kiosk will be attached to the internet you should probably configure it for automatic unattended updates. when the installer drops you into aptitude to add additional packages, don't add any (the ones listed are those on the CD only, which doesn't contain the chromium browser we'll be using).

Install Chromium

After it's running, install the chromium-browser and xinit packages and all their dependencies:

$ sudo apt-get install chromium-browser xinit

Configure Kiosk Account

Create a kiosk user without any ability to login:

$ sudo adduser --disabled-login --shell /usr/bin/startx --gecos 'Kiosk User' kiosk

You may need to add /usr/bin/startx to /etc/shells if adduser complains, or just edit the shell setting for the kiosk user in the /etc/passwd file later, which is what I actually did.

Create a .xinitrc file for the kiosk user. For safety mine is owned by my admin username, not by the kiosk user:

$ sudo touch ~kiosk/.xinitrc
$ sudo chown admin.admin ~kiosk/.xinitrc

It contains this:

#!/bin/sh
/usr/bin/chromium-browser --kiosk 'https://www.wherever.you/want/it/to?start'

If you're paranoid about security you could also change the ownership of some of the other kiosk startup files such as .profile, .bashrc etc.

Configure Automatic Startup

Now we just have to arrange for the kiosk user to be automatically logged in on the first VT at startup. If you are currently using the first VT (pretty likely) you need to logout, then press Ctrl+Alt+F2 and login again there using the admin account before continuing!

Stop the tty1 service to avoid errors:

$ sudo initctl stop tty1

Now edit the /etc/init/tty1.conf file, adding an autologin flag to the /sbin/getty arguments (this is the only line I changed, there are several others in that file which should not be modified):

exec /sbin/getty -8 --autologin kiosk 38400 tty1

Now restart the tty1 service:

$ sudo initctl start tty1

At this point your kiosk user should start the X11 server and the console will switch to VT7. Use Ctrl+Alt+F2 to get back to your logged in session, and Ctrl+Alt+F7 to the X11 session. You may want to use Ctrl+Alt+F1 to look at any errors from your .xinitrc script too.

Configuration Adjustments

If you need to edit the ~kiosk/.xinitrc or /etc/init/tty1.conf files you should probably stop the tty1 service first:

$ sudo initctl stop tty1

You can comment out the line in the /etc/init/tty1.conf that says "respawn" if you need to debug your .xinitrc script. Pressing Alt+F4 in the browser will cause it to quit, and without the "respawn" the service will then stop.

If you find that the chromium browser window does not fill up the screen, you may have to edit the preferences file.

$ sudo vi ~kiosk/.config/chromium/Default/Preferences

This file is in JSON format so it is all text, although it's all on one line so some editors may have difficulty with it. Search for the key "window_placement" and change its sub-keys as appropriate for your display. I also changed "maximized" to "true" (the --kiosk flag is supposed to do that but evidently doesn't).

If your kiosk system has a keyboard your users will be able to cause the browser to quit by pressing Alt+F4. However that should just restart the X server and the browser will then reconnect to the initial URL. My kiosk has a touch-screen (DELL S2240T) which works well with X11, so I can hide the keyboard. Your BIOS may have a setting that lets you unplug it and run without having any keyboard connected at all.

On my system the Power button causes Linux to shut down nicely, but when chromium next starts it puts up a small dialog box at the top right asking if I want to restore the previous session. To stop that I added the following lines to my ~kiosk/.xinitrc file before it starts the browser:

sed -i 's/"exit_type":"Crashed"/"exit_type":"Normal"/' .config/chromium/Default/Preferences
sed -i 's/"exited_cleanly":false/"exited_cleanly":true/' .config/chromium/Default/Preferences

Note that the X11 screen saver defaults to running after about 10-15 minutes of inactivity, which is perfect for my application.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment