docs: Add section build images

This section shows how to build and test images

Signed-off-by: Sietze van Buuren <s.van.buuren@gmail.com>

docs/build-images/build-in-docker.md

@@ -0,0 +1,52 @@
+# Build in Docker
+
+To make sure that the host system configuration does not interfere with a
+simple-CDD build, it's useful to build the image inside a docker container. The
+following lists instructions to setup such a docker image.
+
+## Install and configure docker
+
+First, install and configure docker. Please refer to the script
+[setup_docker.sh](https://github.com/swvanbuuren/simple-cdd-yaml-recipes/blob/master/scripts/setup_docker.sh)
+on how to do this.
+
+## Dockerfile
+
+First create a file called `Dockerfile` with the contents below. Replace
+`<dist>` with the Debian version for which you'd like to build your image, e.g.
+`buster`, `bullseye` or `bookworm`:
+
+```docker
+FROM debian:<dist>-slim
+
+RUN apt-get update
+RUN apt-get -y install --install-recommends simple-cdd xorriso gpg
+
+RUN useradd -ms /bin/bash user
+USER user
+WORKDIR /home/user
+```
+
+## Build docker image
+
+Build the docker image with the following command (again replace `<dist>`):
+```bash
+docker build -t <dist>-simple-cdd .
+```
+
+## Call simple-cdd inside docker
+
+For repeated build attempts, it makes sense to wrap the dockerized simple-CDD
+call into a bash script e.g. called `docker_simple_cdd` (don't forget to replace
+`<dist>` and make the script executable using `chmod +x docker_simple_cdd`):
+```bash
+#!/bin/bash
+ARGS="$@"
+docker run -it --mount "type=bind,source=$(pwd),destination=/home/user" <dist>-simple-cdd /bin/sh -c "simple-cdd $ARGS"
+```
+
+Now you can build an image e.g. from the desktop profile by issuing:
+
+```bash
+./docker_simple_cdd --profiles desktop
+```

docs/build-images/build-with-debos.md

@@ -0,0 +1,37 @@
+# Build with Debos
+
+While the [test method with Qemu](test-on-qemu-with-uefi.md) tests all
+installation image functionalities, it can be quite time consuming. An
+alternative approach is to generate a [debos](https://github.com/go-debos/debos)
+recipe from a Simple-CDD-YAML recipe and build and test its resulting image.
+Building a debos image is generally much quicker and once built, does not
+perform an installation process. Instead, the image can be tested straight away.
+
+To generate a debos recipe, e.g. for the `desktop` recipe, issue the following:
+
+```bash
+simple-cdd-yaml --recipe recipes/desktop.yaml --debos
+```
+
+This will create debos recipe `desktop.yaml` along with all required scripts and
+overlays in the `debos/desktop` directory.
+
+To build the image, move into this directory and build using:
+```
+debos -m 8192MB --debug-shell desktop.yaml
+```
+Note that, depending on the recipe, the increased memory argument (`-m 8192MB`)
+might not be required. 
+
+After the image has been built successfully, it can be tested by starting it in a Qemu environment, e.g. using the following command.
+
+```bash
+qemu-system-x86_64 \
+    -m 2048 \
+    -enable-kvm \
+    -cpu host \
+    -drive if=pflash,format=raw,readonly,file=/usr/share/ovmf/OVMF.fd \
+    -drive if=virtio,format=qcow2,cache=unsafe,file=debian-bookworm-amd64.qcow2
+```
+Please note that, depending on the recipe, the image name
+`debian-bookworm-amd64.qcow2` might be different.

docs/build-images/index.md

@@ -0,0 +1,12 @@
+# Build images
+
+While this documenation is mostly about Simple-CDD-YAML, this section also
+provides some advices for building and testing images with Simple-CDD from the
+profiles that simple-CDD-YAML created.
+
+This includes building [standard Simple-CDD images inside a docker
+container](build-in-docker.md) (these include the Debian installer) and [testing
+them with Qemu](test-on-qemu-with-uefi.md).  
+It also includes the creation of ready-to-go [images built with
+Debos](build-with-debos.md) (without the installer), that can be used for
+quickly testing the image's functionality e.g. in a VM.

docs/build-images/test-on-qemu-with-uefi.md

@@ -0,0 +1,79 @@
+# Test on Qemu with UEFI
+
+The exemplary [desktop
+recipe](https://github.com/swvanbuuren/simple-cdd-yaml-recipes/blob/master/recipes/desktop.yaml)
+creates a Simple-CDD profile for an UEFI capable desktop system. While
+Simple-CDD [offers a qemu
+option](https://salsa.debian.org/debian/simple-cdd/-/blob/master/README?plain=1#L49)
+to test the installation of a CD or DVD created with Simple-CDD, it does not
+support UEFI. The following shows how to boot a Qemu with UEFI support in order
+to test the installation in EFI mode. 
+
+## Prerequisites
+
+The following setup is meant for Debian systems and was tested on Debian Bullseye.
+
+## Preparations
+
+In order to be able to build an ISO image, first install the required packages
+for Simple-CDD:
+```
+sudo apt install simple-cdd xorriso
+```
+Then build an image from the desktop profile:
+```
+build-simple-cdd --profiles desktop
+```
+This should produce an ISO file in the folder `images`.
+
+Please refer to the [Simple-CDD website](https://salsa.debian.org/debian/simple-cdd) and the
+corresponding [Debian Wiki Simple-CDD Howto page](https://wiki.debian.org/Simple-CDD/Howto)
+for more information.
+
+## Setup Qemu
+
+To test the installation image Qemu can be used. Install the required packages
+using:
+```
+sudo apt install qemu-utils qemu-system-x86 ovmf qemu-system-gui
+```
+The package `ovmf` is required for UEFI support.
+
+Now create some images for testing, e.g.
+```
+qemu-img create -f qcow2 disk.qcow2 10G
+qemu-img create -f qcow2 second_disk.qcow2 10G
+```
+Create a bash script stored as `image_run` with the following contents (don't
+forget to make it executable using `chmod +x image_run`)
+
+```bash
+#!/bin/bash
+if [ $# -eq 0 ] ; then
+    cdrom="-boot c"
+else
+    cdrom="-boot d -drive media=cdrom,readonly=on,file=${1}"
+fi
+qemu-system-x86_64 \
+    -m 2048 \
+    -enable-kvm \
+    -cpu host \
+    ${cdrom} \
+    -drive if=pflash,format=raw,readonly=on,file=/usr/share/ovmf/OVMF.fd \
+    -drive format=qcow2,file=disk.qcow2 \
+    -drive format=qcow2,file=second_disk.qcow2
+```
+
+## Testing using Qemu
+
+Test the Simple-CDD installation by issuing (replace `<simple-cdd-iso>` with the
+iso file as created by Simple-CDD):
+```
+./image_run images/<simple-cdd-iso>
+```
+After the installation has been completed succesfully, test out the installed
+desktop system using 
+
+```
+./image_run
+```

docs/index.md

@@ -3,10 +3,12 @@
 Welcome to the documentation of
 [Simple-CDD-YAML](https://github.com/swvanbuuren/simple-cdd-yaml)!
 
-Have a look at the [introduction](introduction.md) to get a quick idea of what Simple-CDD-YAML
-is and what it can do.
+Have a look at the [introduction](introduction.md) to get a quick idea of what
+Simple-CDD-YAML is and what it can do.
 
 To get going follow the instructions in [getting started](getting_started.md).
+Instructions for building and testing images are provided in the section [build
+images](build-images/)
 
 The [examples](examples.md) page features a simple example of a `YAML` recipe.
 

mkdocs.yml

@@ -40,6 +40,11 @@ nav:
     - Getting started: getting_started.md
     - Installation: installation.md
     - Examples: examples.md
+  - Build images:
+    - build-images/index.md
+    - Build in Docker: build-images/build-in-docker.md
+    - Test on Qemu with UEFI: build-images/test-on-qemu-with-uefi.md
+    - Build with Debos: build-images/build-with-debos.md
   - Code Reference:
     - reference/index.md
     - Simple-CDD-YAML: reference/simple_cdd_yaml.md