Opinionated Debian Installer

This tool can be used to create a modern installation of Debian. Our opinions of what a modern installation of Debian should look like in 2024 are as follows:

• Debian 12 (Bookworm)
• Backports and non-free enabled
• Firmware installed
• Installed on btrfs subvolumes
• Full disk encryption, unlocked by TPM
• Fast installation using an image
• Browser-based installer

Limitations

• The installer will take over your whole disk
• Amd64 with EFI only
• The installer is in english only
• Secure boot is not supported

Downloads

Instructions

1. Download one of the live image files from the table above
2. Write the image file to a USB flash drive. Do not use ventoy or similar "clever" tools - they are not compatible with these images. If you need a GUI, use etcher or win32DiskImager or just use dd - dd if=opinionated-debian-installer*.img of=/dev/sdX bs=8MB status=progress conv=sync where sdX is your USB flash drive
3. Boot from the USB flash drive
4. Start the installer icon from the desktop/dash, fill in the form in the browser and press the big Install button
5. Reboot and enjoy

Screencast & Screenshot

Video of installation of Debian with KDE Plasma:

Screenshot of the full installer GUI:

Details

• GPT disk partitions are created on the designated disk drive:
  • UEFI ESP partition
  • Optional swap partition - LUKS encrypted
  • Root partition - LUKS encrypted (rest of the drive)
• GPT root partition is auto-discoverable
• Btrfs subvolumes will be called @ for / and @home for /home (compatible with timeshift); the top-level subvolume will be mounted to /root/btrfs1
• The system is installed using an image from the live iso. This will speed up the installation significantly and allow off-line installation.
• Dracut is used instead of initramfs-tools
• Systemd-boot is used instead of grub
• Network-manager is used for networking
• Systemd-cryptenroll is used to unlock the disk, using TPM (if available)
• Sudo is installed and configured for the created user

(Optional) Configuration, Automatic Installation

Edit installer.ini on the first (vfat) partition of the installer image. It will allow you to pre-seed and automate the installation.

If you edit it directly in the booted installer image, it is /boot/efi/installer.ini Reboot after editing the file for the new values to take effect.

Headless Installation

You can use the installer for server installation.

As a start, edit the configuration file installer.ini (see above), set option BACK_END_IP_ADDRESS to 0.0.0.0 and reboot the installer. There is no encryption or authentication in the communication so only do this on a trusted network.

You have several options to access the installer. Assuming the IP address of the installed machine is 192.168.1.29 and you can reach it from your PC:

• Use the web interface in a browser on a PC - open http://192.168.1.29/opinionated-debian-installer/

• Use the text mode interface - start opinionated-installer-tui -baseUrl http://192.168.1.29:5000

• Use curl - again, see the installer.ini file for list of all options for the form data in -F parameters:

  curl -v -F "DISK=/dev/vda" -F "USER_PASSWORD=hunter2" \ -F "ROOT_PASSWORD=changeme" -F "LUKS_PASSWORD=luke" \ http://192.168.1.29:5000/install

• Use curl to prompt for logs:

  curl http://192.168.1.29:5000/download_log

Testing

If you are testing in a virtual machine, attaching the downloaded image file as a virtual disk, you need to extend it first. The image file that you downloaded is shrunk, there is no free space left in the filesystems. Use truncate -s +500M opinionated*.img to add 500MB to the virtual disk before you attach it to a virtual machine. The installer will expand the partitions and filesystem to fill the device.

Libvirt

To test with libvirt, make sure to create the VM with UEFI:

1. Select the Customize configuration before install option at the end of the new VM dialog
2. In the VM configuration window, Overview tab, Hypervisor Details section, select Firmware: UEFI

To add a TPM module, you need to install the swtpm-tools package.

Attach the downloaded installer image file as Device type: Disk device, not CDROM device.

Hyper-V

To test with the MS hyper-v virtualization, make sure to create your VM with Generation 2. This will enable UEFI. TPM can be enabled and Secure Boot disabled in the Security tab of the Hyper-V settings.

You will also need to convert the installer image to VHDx format and make the file not sparse. You can use qemu-img (windows download) and fsutil like this:

qemu-img convert -f raw -O vhdx opinionated-debian-installer-bookworm-kde-plasma-20230319a.img odin.vhdx
fsutil sparse setflag odin.vhdx 0

Attach the generated VHDx file as a disk, not as a CD.

Hacking

Alternatively to running the whole browser based GUI, you can run the installer.sh script manually from a root shell. The end result will be exactly the same. Just don't forget to edit the configuration options (especially the DISK variable) before running it.

Creating Your Own Installer Image

1. Insert a blank storage device
2. Edit the DISK variable at the top of files make_image_*.sh
3. Execute the make_image_*.sh files as root

In the first stage of image generation, you will get a tasksel prompt where you can select a different set of packages for your image.

Installer Image Structure

There are 3 GPT partitions on the installer image:

1. EFI boot partition
2. Base Image - Btrfs partition with maximum zstd compression. When the live system is running, this is used as a read-only lower device for overlayfs. When installing the target system, the installer will copy this to the target system, mount it read-write, resize to expand to the whole partition and continue with the system installation.
3. Top Overlay - upper and work device for the overlayfs for the live system. The changes you make while the live system is running are persisted here.

Building the Front-End

The front-end is a vue application. You need npm to build it. Run the following commands to build it:

cd frontend
npm run build

Building the Text-User-Interface Front-end

The TUI front-end is a go application. Run the following commands to build it:

cd frontend-tui
go build -o opinionated-installer-tui

Configuration Flow

flowchart LR
    A[installer.ini] -->|EnvironmentFile| B(installer_backend.service)
    B -->|ExecStart| C[backend.py]
    D(Web Frontend) --->|HTTP POST| C
    E(TUI Frontend) --->|HTTP POST| C
    G(curl) --->|HTTP POST| C
    C -->|environment| F[installer.sh]

Output Flow

flowchart RL
    C[backend.py] -->|stdout| B(installer_backend.service)
    C --->|websocket| D(Web Frontend)
    C --->|websocket| E(TUI Frontend)
    C --->|HTTP GET| G(curl)
    F[installer.sh] -->|stdout| C

Comparison

The following table contains comparison of features between our opinionated debian installer and official debian installers.

[1] /boot needs a separate unencrypted partition

[2] @ and @home (timeshift compatible)

[3] @rootfs

[4] Fixed partitioning (see Details above), LUKS is automatic, BTRFS is used as filesystem