Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Create a webapp kiosk with a Raspberry Pi 3

Raspberry Pi 3 B Kiosk

This guide utilizes Raspbian Jessie Lite as a base to create a kiosk that loads a single-page web app in the Chromium browser.

Prepare Micro SD Card

  1. Download and unzip Raspbian Jessie Lite.
  2. Copy the img file to the micro SD card. For platform-specific instructions, you can look here. If using Linux or MacOS, my preference is to use dd as described below.

Using dd

  1. Run lsblk -p before and after inserting your card to find the correct path to your card. Be absolutely sure to get this right because dd will DESTROY everying it writes over, and there are no limits to where it can write.
  2. Copy img file to card: sudo dd if=PATHTODOWNLOADEDIMG of=PATHTOCARD bs=1M status=progress

Your card should now be ready to boot and configre as a kiosk.

Configure Kiosk

  1. Insert the card into the RPI and boot it up.

  2. Log in with default username pi and password raspberry.

  3. Raspbian now disables SSH by default (preventing RPI botnets), so you will need to run sudo raspi-config directly on the machine.

    • Change User Password (Give it a good password: this is root access!)
    • Interfacing Options --> SSH (enable SSH)
    • Localisation Options --> Change Timezone (set to your timezone)
    • Expand Filesystem
    • Finish (and sudo reboot)
  4. Note IP address of device, then SSH into it (this will allow copy & pasting from this file): ssh pi@IPADDRESS

  5. Update OS and install needed packages (this will take a LONG time): sudo apt-get update && sudo apt-get --yes --force-yes dist-upgrade && sudo apt-get --yes --force-yes install xorg nodm chromium-browser xautolock numlockx

  6. If you want WiFi, edit the config file: sudo nano /etc/network/interfaces

    • Comment out the existing wlan0 and wlan1 and add a new config for wlan0:

      auto wlan0
      iface wlan0 inet dhcp
      wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
      wpa-ssid YOURSSID
      wpa-psk YOURKEY
    • Save the file by pressing ctrl-x , then y and enter.

  7. Create the kiosk user: sudo useradd -G www-data -m kiosk && sudo passwd kiosk

  8. Create an .xsession file for the kiosk user: sudo nano /home/kiosk/.xsession

    Paste this into the editor (usually shift-ctrl-v or shift-insert, or use the right-click context menu):

    #!/usr/bin/env bash
    # Set your app's URL below:
    xset s off
    xset -dpms
    xset s noblank
    sed -i 's/"exited_cleanly": false/"exited_cleanly": true/' ~/.config/chromium/Default/Preferences
    numlockx on
    #Lock out right-click and menu button on keyboard
    xmodmap -e "pointer = 1 2 32 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31"
    xmodmap -e "keycode 135 ="
    #Lock out other special keys
    xmodmap -e "keycode 64 ="       #L-alt
    xmodmap -e "keycode 108 ="      #R-alt
    xmodmap -e "keycode 37 ="       #L-ctrl
    xmodmap -e "keycode 105 ="      #R-ctrl
    xmodmap -e "keycode 133 ="      #L-windows (meta key)
    xmodmap -e "keycode 134 ="      #R-windows (meta key)
    xmodmap -e "keycode 107 ="      #print-screen
    xmodmap -e "keycode 127 ="      #page-break
    xmodmap -e "keycode 77 ="       #num-lock
    xmodmap -e "keycode 78 ="       #scroll-lock
    xmodmap -e "keycode 118 ="      #insert
    xmodmap -e "keycode 9 ="        #esc
    xmodmap -e "keycode 67 ="       #F1
    xmodmap -e "keycode 68 ="       #F2
    xmodmap -e "keycode 69 ="       #F3
    xmodmap -e "keycode 70 ="       #F4
    #xmodmap -e "keycode 71 ="       #F5
    xmodmap -e "keycode 72 ="       #F6
    xmodmap -e "keycode 73 ="       #F7
    xmodmap -e "keycode 74 ="       #F8
    xmodmap -e "keycode 75 ="       #F9
    xmodmap -e "keycode 76 ="       #F10
    xmodmap -e "keycode 95 ="       #F11
    xmodmap -e "keycode 96 ="       #F12
    # Restart chromium after 10 minutes of inactivity (this helps with page reloads, etc.)
    xautolock -secure -time 10 -locker /home/kiosk/ &
    # Auto-detect resolution and store in variables
    res=$(xdpyinfo -d :0 | grep dimensions | sed -r 's/^[^0-9]*([0-9]+x[0-9]+).*$/\1/')
    resx=$(echo $res | awk '{split($0,array,"x")} END{print array[1]}')
    resy=$(echo $res | awk '{split($0,array,"x")} END{print array[2]}')
    while true; do
      chromium-browser --incognito --noerrdialogs --window-size=$resx,$resy --window-position=0,0 --kiosk $SPA_URL;
      sleep 1s;

    Make any changes to the config as needed, at least setting the SPA_URL.

    Save the file by pressing ctrl-x , then y and enter.

  9. Create a simple script to kill Chromium: echo "pkill chromium" | sudo tee /home/kiosk/

  10. Make the script executable: sudo chmod +x /home/kiosk/

  11. Edit the nodm config file: sudo nano /etc/default/nodm

  • Change as needed to match the following two settings: NODM_ENABLED=true and NODM_USER=kiosk
  • If you wish to disable the mouse pointer entirely, you can use this option: NODM_X_OPTIONS='-nolisten tcp -nocursor'
  • Save the file by pressing ctrl-x , then y and enter.
  1. Optional Stuff
  • You can use xbindkeys to attach scripts to keys if you want to add custom functionality.

  • You can add a cron job to reboot the kiosk regularly: sudo crontab -e

    Choose nano and edit the cron file by adding the following to the bottom of the file:

    0 4 * * * /sbin/shutdown -r now

    Save the file by pressing ctrl-x , then y and enter.

  1. You are done! Reboot the kiosk and it should boot into your app: sudo reboot
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment