On-device installer

The on-device installer provides a graphical interface to configuring the operating system before it gets installed.

Features

 * Install any mobile OS, not just postmarketOS
 * Full disk encryption (optional)
 * Set the user password (numeric PIN, as expected by Phosh and Plasma Mobile)
 * Set up a dedicated ssh user (optional) (related: )
 * Choice between installing to eMMC or SD card.

It's far from perfect, but what's there works reliably and should give a good mobile installer base to iterate upon.

Overview
The on-device installer is dual-booting between the installer OS and target OS.

Installer OS is the operating system running Calamares with the mobile module. In theory, any OS could be used as installer OS. However, postmarketOS as installer OS should be the most straight forward way, so it's highly recommended to produce a working image with that first. This article assumes that postmarketOS is the installer OS.

postmarketos-ondev (repo, packaging) holds the postmarketOS specific installer OS configuration.

Target OS is the operating system that will be installed. It must be able to:
 * unlock encrypted partitions on boot, with osk-sdl or similar (source, pmOS, Debian)
 * extend rootfs space on first boot
 * delete the installer OS partition (pmOS)
 * extend the root partition over all unallocated space (pmOS)

pmbootstrap init
Install pmbootstrap. Run  and select the device you would like to install. The selected UI is only relevant if postmarketOS is the target OS. Everything else can be left at default values.

Note that you can automate above step as follows:

If the target OS is not postmarketOS, set the boot partition to at least the size of the boot partition of the target OS (in MiB):

If you run into "not enough free space" errors later on, you can add extra free space to the rootfs image too (in MiB).

Debug user
Before the generation of the image is explained, a quick note on the debug user. The installer OS will have a debug user with the username  and password. This user is created in the installer OS, but of course not in the target OS. The installer OS also has SSH enabled by default and listens on all interfaces. You can login as the debug user either via serial, or with SSH over USB Network.

Consider disabling the debug user in production images, if you expect the target device to be available on a network (e.g. Raspberry Pi). To disable the debug user, install a file to :

postmarketOS as target OS
More or less, the following command. See  for details.

Foreign target OS
Create a working directory like, where you store the configuration files below. These will be placed in the installer OS with the  command listed even further below.

mobile.conf
Create a  based on the reference. The  will be filled out automatically (the line must exist in the config though).

shellprocess.conf
postmarketos-ondev configures Calamares to run the shellprocess module at the very end of the installation. Prepare a :

pmbootstrap install
Download the target OS image and extract it if necessary. postmarketos-ondev expects a foreign target OS image to have two partitions, boot and rootfs.

Once all files are ready, run the following command. The last line is optional for integrating the target OS logo into the installer. Leave them out if you just want to test this and don't have the logo in the right format.

The resulting image file is here:

Running in QEMU
You can get a relatively short test cycle by running everything in QEMU (1-2 minutes to build the new install image, run the whole installation and reboot into the target OS).

For the first install, configure pmbootstrap and build the postmarketOS target rootfs with UI=none.

For all following installs, use  to save time.

Building components from source
This section describes how to build packages for various components from their local git trees. will use these versions instead of the official binary packages. Run  to delete all previously built packages.

Packages will get usually get built for the host arch. Add  or similar to each   line if necessary.

How it works
does the following:
 * prepares the device rootfs, and create an image from it as usually (more or less)
 * prepares a new installer rootfs
 * copies the device rootfs image into the installer rootfs as /var/lib/rootfs.img
 * installs postmarketos-ondev, postmarketos-base and the device-package into the installer rootfs
 * runs ondev-prepare.sh
 * creates an image from the installer rootfs, with reserved space

The installer image has the following partition layout:
 * p1: label=pmOS_boot
 * p2: (reserved space)
 * p3: label=pmOS_install

This installer image can be transmitted to the device via the usual methods (fastboot flash, via SD card, ...). When booting into the installer's initramfs, the usual postmarketOS initramfs code will prefer  over   (so we don't end up in an invalid state if an installation was aborted). So the  partition will be mounted as / and the boot continues.

ondev-boot.sh runs:
 * calculates ONDEV_PARTITION_TARGET
 * configures tinydm and i3, then starts tinydm (we may use something other than i3 in the future, but this works well even with framebuffer devices)
 * the config will start Calamares

Calamares runs:
 * loads settings.conf
 * shows the custom mobile module
 * this module asks for the FDE password, formats the target partition with cryptsetup and ext4 and mounts it (bypassing some of the usual Calamares logic, as Calamares relies on grub2 and encrypted initramfs)
 * "unpackfs" extracts rootfs.img and gives a nice progress bar
 * "shellprocess" renames pmOS_install to pmOS_deleteme and reboots (also replaces boot partition in foreign target OS case)

The partition layout looks like this now:
 * p1: label=pmOS_boot
 * p2: label=pmOS_root
 * p3: label=pmOS_deleteme

postmarketOS initramfs does the following as target OS during first boot:
 * deletes the pmOS_deleteme partition
 * resizes pmOS_root to use up all available free space (even beyond pmOS_deleteme)
 * runs osk-sdl as usually for encrypted installations
 * boots into pmOS_root

Related

 * postmarketos-ondev issues
 * plans for upstreaming to Calamares
 * Screenshots in the PinePhone pre-order blog post
 * Initial commit message
 * On-device installer
 * Why installers are needed for disk encryption, explaining the FDE parts