On-device installer

From postmarketOS
Jump to navigation Jump to search

The on-device installer postmarketos-ondev allows customizing the postmarketOS installation without using our command-line tool pmbootstrap. It starts an installer on the device, that guides the user graphically through various installation settings. With Calamares, which you may know from desktop Linux distribution installations. Most importantly, this makes it possible to perform a full disk encrypted installation from a pre-built image.


The most important dialogs have been implemented (user pin, ssh credentials, full disk encryption password). For now, the target partition for the installation will always be the reserved space on the same "disk" as the installer (details below). We can add support for installing from SD card to internal memory in the future. Find and report issues here. It's planned to upstream the custom modules to Calamares.


$ pmbootstrap init
$ pmbootstrap install --ondev [--sdcard]

How it works

pmbootstrap install --ondev 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 pmOS_install over pmOS_root (so we don't end up in an invalid state if an installation was aborted). So the pmOS_install partition will be mounted as / and the boot continues.

ondev-boot.sh runs:

  • configures lightdm and i3, then starts lightdm (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 "pmos" module (to be renamed to "mobile" and split up)
  • 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

The partition layout looks like this now:

  • p1: label=pmOS_boot
  • p2: label=pmOS_root
  • p3: label=pmOS_deleteme


  • deletes the pmOS_deleteme partition (postmarketos-ondev#1)
  • 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


Building postmarketos-ondev with a local source tree

$ cd ~/code/postmarketos-ondev
$ pmbootstrap --details-to-stdout build --src=. postmarketos-ondev

Running postmarketos-ondev locally

Run it in a chroot (test UI changes):

$ pmbootstrap chroot --xauth --add=postmarketos-ondev,mesa-dri-gallium -- sh -c "QT_IM_MODULE=qtvirtualkeyboard calamares -D8"

Or run it in QEMU (test the whole installation):

$ pmbootstrap config device qemu-amd64
$ yes | pmbootstrap install --ondev
$ pmbootstrap qemu

Enable SSH server

This is currently possible by checking out postmarketos-ondev, commenting in this line and building it as described above. Don't forget to set the right arch (i.e. pmbootstrap build --src=. --arch=armv7 postmarketos-ondev).