Development Resources

This page is dedicated to those who wish to either help develop HalogenOS, or host their own build infrastructure to distribute modified versions of HalogenOS.

Build System

HalogenOS images are built and signed using a Docker container and a build script. The Docker container provides the necessary Gentoo tooling (emerge, Portage, profiles, compilers, libraries, etc) to compile all the system's binaries. The script contains all the commands necessary to copy over relevant config files, compile all the needed binaries, and create a system partition image.

Installation

Currently, there is no "installer" for HalogenOS. Installation must be performed manually from a Linux live USB:

A 512mb EFI boot partition must be created.
The kernel UKI and the A/B boot manager must be placed in this partition.
A system image must be installed in the disk immediately following the EFI partition.
The system EFI must have Secure Boot enabled and set to Setup Mode.

Upon reboot, the first system slot (Slot A) will generate its own verity partition, Slot B's system and verity partitions, and the root partition. It will also generate Secure Boot Keys and sign all EFI binaries, effectively relocking the system's firmware security mechanisms by exiting Setup Mode. For full security, the system BIOS password must be set. Once Secure Boot is finalized, the root partition's password will be bound to the TPM.

Eventually, this project will include an installation script that could be used from an Arch Linux or Alpine Linux minimal ISO.

OTA Updates

HalogenOS OTA updates are designed to function regardless of who is building and distributing the OS. However, the URL scheme is important, as there are several components that might change in the future or gain additional variants (like the DE or the architecture).

An example URL scheme might look like this:

https://example.com/halogenOS/$ARCH/$IMAGE_ID/

The $ARCH and $IMAGE_ID variables will remain as x86_64 and desktop for the time being- they serve as placeholders for now.

At the root of this directory, there must be a file titled manifest.env. It should define a few variables, like so:

ALPHA=2025091101
BETA=2025091001
STABLE=2025090801
PUBKEY=somekeyname.pgp

If the distributor does not want to provide separate release channels, they must at least define a stable release entry which should point to the newest viable release. Stable is the default.

If release signing is enabled, there must also be a valid PGP public key in that directory, which must correspond to the private key used to sign the release files. The release signing keys must never change, and HalogenOS build scripts must not be modified to allow the generation of images which would accept an update signed with a different public key than the one on-disk. The filename of the public key must correspond with the PUBKEY variable in the manifest.env file.

Furthermore, the server must contain within that directory, a separate subdirectory for each release, with the directory name being the release number. Inside that directory should be two files:

A .tar.gz archive generated by the build script. The filename must be solely the version number and the .tar.gz extension.
A valid PGP signature of the tarball. The filename must be the name of the tarball file, appended with .pgp.

Optionally, there may be subdirectories named after the release channels (stable, beta, alpha), which are symbolic links to the versions in those channels.

Security

Public-key cryptography is used to ensure that system images are not tampered with in transit, and to increase assurance that kernel modules are authorized to run on the system. The image distribution key must be consistent across releases, or else the system will be unable to update to any other version. Kernel keys should preferably remain the same across versions, but kernel modules must include their kernel target versions to ensure incorrect versions cannot be loaded.

Cryptographic private keys or symmetrical keys cannot, and should not, ever be present in installation images. Signing keys are required to be password-protected, and should also be stored in an encrypted directory or disk. The usage of the Docker secrets API ensures that keys and passwords are never copied out of their original locations. Symmetric encryption keys are always generated dynamically and protected by TPM.