These scripts are used to setup a station serving the RRRRR exhibit.
The target system for running the script is Ubuntu 22.04 provided that the following settings have been applied during installation:
- Choose minimal installation
- Install third-party software for graphics and WiFi hardware... : ON
- Configure secure boot: ON. (set a password; it needs to be entered on first boot)
- Account settings:
- User name:
kiosk
- User name:
- Reboot after installation is complete
- Enroll the secure boot keys using the password you entered during secure boot configuration
- Reboot into the system
The script bin/bootstrap-os will install required packages, the scripts in this repository as
well as most of the exhibits:
wget https://raw.githubusercontent.com/IMAGINARY/rrrrr-scripts/main/bin/bootstrap-os
chmod +x bootstrap-os
sudo ./bootstrap-os
Some changes made by the bootstrapping script might only take effect after a reboot.
The bootstrapping script will ask if it should make the file system immutable after next reboot. This can be very useful to make the whole setup immune to crashes or other modifications of the system. So even if something goes severely wrong during operation, a reboot will usually solve all problems because it resets the system to a well defined state.
The immutable file systems is achieved via overlayroot which writes file modifications to a tmpfs in RAM instead of the local hard disk. Programs that write a lot of data might cause problems since available RAM might be limited.
Immutability can be toggled using the scripts enable-overlayroot and disable-overlayroot. Both require a reboot to take effect.
In immutable mode, changes to the local file system can be performed via the overlayroot-chroot command but this might have unintended consequences since not all system modifications (such as modifications to the bootloader or systemd) work well from within a chroot. So handle with care.
Note that only the root partition is made immutable. It is still possible to write to partitions such as the configuration partition mounted to /cfg.
Important note: The scripts in this repository are designed for initial setup of the system. Using them for installing updates may or may not work reliably and some scripts will reset parts of the station configuration along the way. Running the scripts from within overlayroot-chroot may render the system unusable or even prevent successful booting. You have been warned.
That said: You can either re-run bootstrap-os or reinstall/update individual exhibits via the
install-* scripts. Note that in most cases, install-kiosk-scripts must be executed first
to update the other installation scripts to the most recent version.
It is out of the scope of these scripts to provide facilities for uninstalling. You have to check the installation scripts to figure out how to roll back an installation manually.
Doing so might also be helpful in cases where installations or updates fail. Cleaning previous installations might fix certain issues.
Exhibit start script names are prefixed with exhibt- followed by an identifier of that exhibit. See bin/launch for a list of known exhibits.
The script repeat-exhibit will restart the executable supplied as argument indefinitely, e.g.
repeat-exhibit exhibit-kiosk
will restart exhibit-kiosk if it exits for whatever reason.
All exhibits can be stopped via
stop-exhibits
This includes the repeat-exhibit script and any process whose name starts with exhibit-.
By default, a plain X11 session is started that first runs an init script for the exhibit and then runs the exhibit in a loop with mouse cursor hiding enabled.
The init script is supposed to run only once and it needs to exit once the init tasks are performed. Otherwise, script execution will block and no exhibit will be started.
The system wide default for init and exhibit scripts are defined in /etc/default/kiosk.
User defined values can be provided in the file $XDG_CONFIG_HOME/kiosk/default following the same format as /etc/default/kiosk.
If $XDG_CONFIG_HOME is not set, it's default value ~/.config will be assumed.
In the plain X11 session, there is not much the user can do besides using the running exhibit (which is intended). Basically, the only way to launch (graphical) applications is via one of the virtual terminals (e.g. CTRL+ALT+F2) or via ssh.
It is also possible to leave the plain X11 session and go back to the login screen were you can select another session (e.g. regular Gnome Desktop):
stop-kiosk-session
Note that the selected session will also be used after reboot if the filessystem isn't immutable. Hence, you should switch back to the plain X11 session once your work in the regular desktop session is done.
The script hidecursor hides the cursor and starts another child process supplied as an argument.
When the child exits, the cursor will not be hidden anymore.
Sometimes the display used for development does not match the resolution used in production.
Assume your test display has a default resolution of 1920x1080 (FullHD), but in production, 3840x2160 (UHD) is used.
The command
fakeResolution 3840x2160
will allocate a 3840x2160 frame buffer and will scale it down to 1920x1080.
If aspect ratios do not match, the image will be stretched.