KioskForge is a freeware, open source software (FOSS) program to automate and simplify the process of setting up a new kiosk machine.
KioskForge is intended to be used by somewhat non-technical users to set up a kiosk machine for browsing a given website or by more advanced users to set up a kiosk that runs a CLI or GUI app of the user's choice.
KioskForge takes two inputs:
The first, the Ubuntu Server installation medium, is automatically located by KioskForge, if it is present on the host system. The name of the kiosk file is passed as an argument to KioskForge, which is can be done simply by double-clicking on the file.
KioskForge then modifies the Ubuntu Server installation medium so that the first time a system is booted using it, a kiosk will be created that is ready to be deployed.
The total size of the files that KioskForge adds to the kiosk machine is currently less than 1 MB in total.
KioskForge currently supports these things:
Please notice that the kiosk needs either internet access or a real-time clock (RTC) for its automatic, daily maintenance to work properly. If the kiosk does not have internet access, it should be a Pi 5 with an RTC backup battery, otherwise the kiosk may reboot at seemingly random times because the system clock is wrong. At this time, we cannot recommend using Raspberry Pi 4B without internet access. It is best that the kiosk has internet access all the time or during a fixed, daily interval of time.
Ideally, you use a tool like KeePassXC to manage the passwords to your kiosks and make sure that each kiosk has its own password so that getting access to one kiosk does not automatically grant access to every kiosk that you operate.
To avoid problems with hackers and hostile visitors, you should
always make sure that all kiosks runs on their own,
private subnet (192.168.x.*). This will become much more
important in the future so heed our advice and implement this already
now.
This chapter aims to give you a basic understanding of how use KioskForge.
KioskForge is intended to be used by all sorts of users for which reason it strives to require as little technical knowledge as possible and to automate the creation (forging) of the kiosk as much as possible.
KioskForge works by modifying a supported Ubuntu Server installation
medium according to the settings the user has given in a
.kiosk file (an INI-style configuration file). The format
of the .kiosk file is very simple and does not require
significant technical knowledge. After the installation medium has been
configured by KioskForge, it is inserted into the target machine, which
is then powered on, and the actual "forge process" takes place. Over
less than thirty minutes, the forge process configures, updates,
modifies, and prepares the target kiosk machine to work as a kiosk
machine (on a permanent basis, not requiring any maintenance whatsoever
after the initial deployment).
You can easily open any .kiosk file in KioskForge simply
by double-clicking the file if you have installed KioskForge using the
Windows installer. This is the recommended way of loading a
.kiosk file in KioskForge on Windows systems.
Alternatively, you can supply the path of the kiosk file on the
command-line if starting KioskForge.exe from a console
window.
To create a new, blank .kiosk file, use the
New right-click context menu in Windows Explorer.
To configure your kiosk, edit it using your favorite editor such as
Notepad. You can right-click the file and select
Edit.
NOTE: You cannot use Microsoft Word or
similar word processing software to edit the .kiosk
file.
HINT: Please check every option in the
.kiosk file before you try to forge a kiosk. There are only
about 25 options, all fairly decently documented in the
.kiosk file itself. If you make an error, you'll have to
re-forge a newly prepared kiosk installation medium once again! So,
review the entire kiosk file before you try to forge your first
kiosk.
When you have started KioskForge by double-clicking the kiosk file, you must make sure that the kiosk installation medium, made with Raspberry Pi Imager or Rufus, is inserted into a USB port in your Windows computer, then you simply double-click the kiosk file and KioskForge will quickly modify the installation medium to prepare it for making a new kiosk.
Once KioskForge has updated the kiosk installation medium, it will ask you to safely remove the medium and insert it into the kiosk machine. Just follow the instructions and then power on the kiosk to begin the actual process of forging the desired kiosk.
This chapter explains the current method of installing KioskForge for the first time on a new Windows PC.
Please notice that we recommend specific versions of Python and Raspberry Pi Imager as we want to ensure the best, most efficient experience for you. You are free to try with other versions of these tools, but we cannot guarantee that they work.
Download the most recent version of
KioskForge-x.yy-Setup.exe from KioskForge.org.
Navigate to the Downloads folder and double-click on the
KioskForge-x.yy-Setup.exe file. Follow the prompts to
install. If you have installed KioskForge before, you should probably
skim the CHANGES.html file and see if there are any
important changes.
After this, you can launch KioskForge directly from Windows Explorer,
by double-clicking a .kiosk file.
NOTE: There's currently no point in starting
KioskForge from the Windows Start menu: It will fail because it needs
the name of a kiosk file to open. You can, however, run it from a
console if you are so inclined, insofar you pass the name of a kiosk
file. If you run it from the command-line, you need to add the
apply keyword before the actual path of the
.kiosk file to use.
NOTE: KioskForge.py currently
cannot be run on Linux. This is a planned feature and is
expected to be fixed sometime soon.
Install a recent version of the Python
v3.13+ programming language. On most Linuxes, this can be done with
the system-wide package manager such as apt,
dnf, pacman, and so on. Make sure to install
Python v3.13+. Earlier versions should work fine, especially v3.10+, but
I don't test against these and don't use older versions of Python during
development.
Then fetch KioskForge from GitHub using the following command:
git clone https://github.com/archfrog/KioskForgeYou need to make sure that the script, KioskForge.py,
has execute permissions (use chmod u+x KioskForge.py to
accomplish that), then you can invoke it using
./KioskForge.py.
I don't have access to a Mac computer, so no development or testing is done on this platform. Feel free to port the script and submit a pull request. Please make sure that the result generates a valid, reliable kiosk before submitting the pull request.
KioskForge is currently a console command, but a GUI version is in the works and will be released eventually.
KioskForge currently uses the X11 windowing system when running Chromium (the open source version of Google Chrome). This will be changed eventually so that KioskForge uses the more modern and slightly better supported Wayland windowing system in the kiosk.
KioskForge currently only supports DHCP-assigned LAN IP adresses so there's no way of specifying a fixed LAN IP address. This basically means you need to talk to your network administrator about getting a static DHCP lease for the kiosk machine itself, which is a very good idea, anyway, as you don't want to work blindly if the kiosk suddenly misbehaves and needs fixing.
KioskForge is a simple application that modifies an Ubuntu Server
24.04.x installation medium so that it creates a kiosk from a so-called
"kiosk file" when booted the first time. A kiosk file is a simple
configuration file that is made up of lines that can either be a blank
line, a comment (starts with #), or a field assignment of
the form name=value. Each kiosk file defines a kiosk and
what how the kiosk is to be forged.
The only GUI way to use KioskForge is to double-click a kiosk file
(which ends in .kiosk and has the Windows Explorer file
type KioskForge Kiosk).
If there are one or more errors in the kiosk file, KioskForge will report them, wait for you to hit enter, and then exit.
If there are no errors in the kiosk file, KioskForge will look through all drives in the system to see if it can recognize a valid Linux installation medium. If it finds one, it will ask you to review the settings and then update the medium so that it will create a kiosk the first time that the kiosk machine is booted off that medium.
NOTE: The kiosk MUST be connected to the internet while it is being forged! After this, it can stay offline forever.
It is always best that the kiosk is permanently on the internet so that it can update Chromium, etc. But it can work without.
NOTE: We generally recommend MicroSD cards over USB keys as the latter have a tendency to get very hot and unreliable.
The procedure is as follows:
Ubuntu Server 24.04.x installation media for
Raspberry Pi 4B (ARM64) using a USB key or a MicroSD card:
Ubuntu Server 24.04.x in the subcategory
Ubuntu of the category
Other general-purpose OS. If you do not see
Ubuntu in the Other general-purpose OS list,
Raspberry Pi Imager is to blame. Just wait a few minutes and try again.
Raspberry Pi Imager sometimes bugs out and refuses to display the entire
list of Linux images.Ubuntu Desktop (KioskForge will detect this, though, and
report an error)..kiosk file, and select New,
then KioskForge Kiosk. Please assign the new kiosk file a
meaningful name so that you can easily see what purpose of the kiosk
is.Notepad
(right-click on the kiosk icon and select Edit). Save it
using Ctrl-S.ENTER to continue. To abort, hit
Ctrl-C.ENTER to exit
KioskForge. Press ENTER to continue and exit
KioskForge.Eject
from Windows Explorer to safely disconnect the installation media..kiosk file or report bugs to us.After that, the kiosk should theoretically run nicely and reliably for years and years. However, you may want to log into it, using SSH, once in a while to verify that logs are being rotated, that there is sufficient disk space available, and so on. The kiosk is set up to automatically reclaim as much space as it can, whenever the daily maintenance script runs.
If you SSH into the kiosk or use a local keyboard to log in, you can
use the kiosklog command to view syslog
entries related to KioskForge.
Please report bugs and ideas on KioskForge Issues at GitHub or by mail to the team at KioskForge team. The former is the preferred method, but use whichever method suits you best.
When you report a bug, please first log into the kiosk and run the command shown below to create a ZIP file containing the redacted kiosk files:
su kiosk
# Enter the preconfigured kiosk password (user_code).
cd ~kiosk
KioskForge/KioskReport.pyThis will create the archive ~kiosk/kiosklogs.zip which
you can afterwards download from the kiosk using scp or WinSCP. Please attach the
kiosklogs.zip file to your bug report, be it by mail or via
GitHub.
All sensitive information (comment, user password, Wi-Fi name, Wi-Fi
password, and the public SSH key) have been redacted out of the
.kiosk file before inclusion in the ZIP archive. You can
search the unzipped Kiosk.kiosk file for the string
REDACTED to verify this.
NOTE: If you are uncomfortable submitting the ZIP archive to GitHub, you are more than welcome to send it attached to a mail.