soios/os/readme.md

# OS build system

This is a system for building a customized OS for SOI, based on [Debian Live].

[Debian Live]: https://live-team.pages.debian.net/live-manual/html/live-manual/index.en.html

## Variants

There are multiple variants of the OS for different use cases.

- `training-live` is a live system for training.
- `training-installer` is an installer, which writes the OS to disk instead of running it directly.
  This is intended for installing the laptops owned by SOI only.
  Installation is offline and mostly automated.
- `contestant` is a live system for contests.
  It has additional configuration useful for contests.

The live systems copy the entire OS to RAM while booting, so you can remove the USB stick after booting is finished.
That way, you only need a small number of USB sticks for booting many computers.

All variants support Secure Boot.
However, VirtualBox (contained in the installer variant) only works with Secure Boot disabled.

## How to build an ISO

We run the build inside a Docker container, so you need Docker installed on your host.
Building works on Linux hosts, other OSes are untested.

First, obtain the configuration files and put them in the folder `config`.
These files contain secrets and are thus not committed to the repository.
If you want to create your own config, see the folder `config-example` for examples.

Run the following commands in the repository root folder.
The `--privileged` flag is needed for mounting `/proc` and similar in the target system root.

```bash
mkdir -p osbuild/build
sudo docker pull debian:bookworm
sudo docker run --rm -it --privileged --mount type=bind,source="$(pwd)",target=/work --workdir /work debian:bookworm
```

Inside the container, run the following commands.
Replace `training-live` with the variant you want to build.

```bash
apt-get update
# python3: for build script
# ca-certificates: for downloading files over https
# rsync, cpio: used by live-build
# unzip: for codeblocks plugin
# build-essential, debhelper: for building custom udeb
apt-get install --no-install-recommends python3 ca-certificates live-build rsync cpio unzip build-essential debhelper
cd osbuild/build
python3 ../../os/build.py training-live
```

Once the build is finished, you will find the ISO at `osbuild/build/live-image-amd64.hybrid.iso`.

## Testing in a VM

During development, it's convenient to test the OS in a virtual machine.
Install QEMU on your host.
The following commands should be run outside the docker container.

```bash
# training-live, legacy and EFI boot:
kvm -m 8G -smp 4 -vga virtio -cdrom training-live.iso
kvm -m 8G -smp 4 -vga virtio -cdrom training-live.iso -bios /usr/share/ovmf/OVMF.fd

# training-installer:
qemu-img create -f qcow2 installtarget.qcow2 20G
kvm -m 8G -smp 4 -vga virtio -drive file=training-installer.iso,if=virtio,format=raw,readonly=on -drive file=installtarget.qcow2,if=virtio -bios /usr/share/ovmf/OVMF.fd -smbios type=1,serial=DEMO123

# contestant:
# Add your ssh key to os/config/contestant_authorized_keys
kvm -m 8G -smp 4 -vga virtio -cdrom contestant.iso -bios /usr/share/ovmf/OVMF.fd -nic user,model=virtio-net-pci,hostfwd=tcp:127.0.0.1:2222-:22
ssh -o "UserKnownHostsFile ./local.known_hosts" -p 2222 root@localhost
```

## Features

The configuration is split into layers, which are applied depending on the variant.
Here is a list of features.

- `participant` (all variants)
  - various code editors and other tools
  - VS Code extensions
  - SOI header
  - Code::Blocks template
  - wallpaper
  - default favorite apps
  - default list of keyboard layouts
  - timezone
  - list of locales
  - bootloader background image
- `live` (all live variants)
  - disable lock on blank screen
  - disable software update notifications
- `training-live`
  - automatic login
  - sudo without password
- `training-installer`
  - disable network detection to speed up install
  - preseed most installer questions
  - look up hostname in inventory file from serial number (inventory-hostname udeb)
  - login screen logo
  - login without password for `noauth` group
  - create an admin user with sudo rights and password
  - create a participant user without password
  - add a boot menu item for resetting participant user data
  - install packages for firmware updates and power manager
  - install Gnome Boxes and VirtualBox for running virtual machines
- `contestant`
  - disable bluetooth
  - disable sleep
  - disable some panels in gnome-control-center
  - disable automatic mounting of storage media
  - polkit rules which block changing network settings and mounting storage media (it prompts for the root password)
  - configure NTP
  - install and configure ssh server
  - set root password
  - set `authorized_keys` for root
  - contest WiFi connection
  - automatic login
  - set browser homepage and bookmarks to https://contest.soi.ch
  - Gnome Shell extension which displays the user name in the top bar
  - contest lock Gnome Shell extension
  - some management scripts to be run via ssh
  - some packages for contest admin