Getting started.

Cleanroom is a system for building Linux systems based on Arch Linux. All package names will therefore be Arch packages.

Build Machine Setup

The build machine may be a seperate server or you can build images on the actual machine you intend to deploy the Cleanroom image on.

You will need a folder or subvolume on a BTRFS volume somewhere to proceed.

This is your base folder.

Dependencies

You will also need make sure you have the following packages installed:

• borg
• btrfs-progs
• sbsigntools
• squashfs-tools
• dosfstools
• qemu
• devtools
• ovmf
• binutils
• lsof
• cpio

Work Directory Setup

Create a new folder 'work' in your base folder.

That will be your work directory going forward.

Clrm should not write outside of the work directory, but please consider running the whole thing in a VM or a container to make sure it really does not break anything on your system!

Borg Repository Setup

Create a new borg repository in your base folder. The name must be 'borg_repository' for the examples to work.

borg init borg_repository --encryption=authenticated

Give 'foobar' as a passphrase (or whatever else you want)

Then export that passphrase to the environment.

export BORG_PASSPHRASE=foobar

Environment Variables

You will need to set up the following environment variables. It is recommended that you include these in your .bash_profile on your build machine. Obviously, there are security implications to including you BORG_PASSPHRASE in that file; you will need to decide for yourself if that is a reasonable option.

export CLRM_BASE=/absolute/path/to/your/clrm-checkout

export BASE_DIR=/absolute/path/to/your/base-folder

Building the Example Image

In order to test your setup, it is recommended that you try and build the system-example image in the examples folder of the Cleanroom project.

Then run the following command as root:

"${CLRM_BASE}/clrm" \
    --systems-directory="${CLRM_BASE}/examples" \
    --work-directory="${BASE_DIR}/work" \
    --clear-storage \
    --clear-scratch-directory \
    --repository-base-directory="${BASE_DIR}" \
    system-example

This command will take a while: It will do a Cleanroom installation of Arch Linux according to the system-example definition file.

Feel free to throw in up to four '--verbose' if you want to see lots of text scroll by.

Leave out '--clear-storage' to keep successfully created systems between clrm runs. This can greatly speed up debugging of system definitions.

Once this command is complete, you should have a system image in the borg repository you have set up earlier.

Test with:

borg list borg_repository

There should be one entry starting with 'system-example-' and a recent timestamp.

Test the Image

Extract the image from borg and start it in qemu.

Either fix permissions on the borg repository to allow access for your normal user or make sure that root can start UI applications for this to work:

export BORG_PASSPHRASE=foobar
"${CLRM_BASE}/firestarter" \
    --repository="${BASE_DIR}/borg_repository \
    system-example qemu_boot

This may take a few minutes to run, but, if everything has gone well, it should finish with qemu booting the system-example image! Log in as root user using password root1234

Congratulations! You've built and deployed your first Cleanroom image!

Where to go From Here

Write your own system definition files based on those found here:-)

"${CLRM_BASE}/clrm --list-commands

should list all the pre-defined commands at your disposal.

Firestarter has several export options for the images stored in borg. There will be more details on the deployment page.