Add build-disk documentation (#2164)

* Add build-disk documentation

Signed-off-by: Andrea Mazzotti <[email protected]>

docs/content/en/docs/Creating derivatives/build_disk.md

@@ -2,64 +2,67 @@
 title: "Build disk images with Elemental"
 linkTitle: "Build disk images with Elemental"
 weight: 4
-date: 2023-08-31
+date: 2024-08-20
 description: >
-  This section documents the procedure to build disk images using elemental
+  This section documents the procedure to build disk images using Elemental
 ---
 
-Requirements:
+In order to build a RAW disk image we rely on `elemental build-disk` command. It accepts a YAML file denoting the sources to bundle in the RAW image. In addition it can also overlay custom files or use container images from a registry as packages.
 
-* `qemu-img` utility
-* `elemental` binary
-* elemental runtime dependencies
-
-The suggested approach is based on using the Elemental installer (`elemental install` command) to run the installation
-from a Linux to a loop device. The loop device can be a raw image created with `qemu-img create` that can easily be
-converted to other formats after the installation by using `qemu-img convert`.
-
-## Prepare the loop device
-
-Preparing the a loop device for the installation is simple and straight forward.
+To build a RAW image, just run:
 
 ```bash
-# Create a raw image of 32G
-> qemu-img create -f raw disk.img 32G
-
-# Set the disk image as a loop device
-> sudo losetup -f --show disk.img
-<device>
+docker run --rm -ti -v $(pwd):/build ghcr.io/rancher/elemental-toolkit/elemental-cli:latest --debug build-disk --expandable --unprivileged --squash-no-compression -o /build $SOURCE
 ```
 
-## Run elemental installation
-
-Execute the elemental installation as described in [installing](../../getting-started/install):
-
-```bash
-> sudo elemental install --firmware efi --system.uri oci:<image=ref> <device>
+Argument `$SOURCE` might be the reference to the directory, file, container image or channel we are building the ISO for, it should be provided as uri in following format <sourceType>:<sourceName>, where:
+    * <sourceType> - might be ["dir", "file", "oci", "docker"], as default is taken "docker"
+    * <sourceName> - is path to file or directory, channel or image name with tag version (if tag was not provided then "latest" is used)
+
+`elemental build-disk` command also supports reading a configuration `manifest.yaml` file. It is loaded form the directory specified by `--config-dir` elemental's flag.
+
+An example of a yaml file using the bootloader from the contained image:
+
+```yaml
+# Representing the RAW disk final image name without including the '.raw'
+name: "Elemental-0"
+# Indicates if the output image name has to contain the date
+date: true
+# Folder destination of the built artifacts. It attempts to create if it doesn't exist.
+output: /output/dir
+# Snapshotter configuration
+snapshotter:
+  type: btrfs
+  maxSnaps: 2
 ```
 
-Where `<image-ref>` is the Elemental derivative container image we want to use for the disk creation and `<device>` is the
-loop device previously created with `losetup` (e.g. `/dev/loop0`).
-
-
-## Convert the RAW image to desired format
-
-Once the installation is done just unsetting the loop device and converting the image to the desired format is missing:
-
-```bash
-# Unset the loop device
-> sudo losetup -d <device>
-
-# Convert the RAW image to qcow2
-> qemu-img convert -f raw -O qcow2 disk.img disk.qcow2
+### Usage
+
+```text
+Usage:
+  elemental build-disk image [flags]
+
+Flags:
+  -c, --cloud-init strings               Cloud-init config files to include in disk
+      --cloud-init-paths strings         Cloud-init config files to run during build
+      --cosign                           Enable cosign verification (requires images with signatures)
+      --cosign-key string                Sets the URL of the public key to be used by cosign validation
+      --date                             Adds a date suffix into the generated disk file
+      --deploy-command strings           Deployment command for expandable images (default [elemental,--debug,reset,--reboot])
+      --expandable                       Creates an expandable image including only the recovery image
+  -h, --help                             help for build-disk
+      --local                            Use an image from local cache
+  -n, --name string                      Basename of the generated disk file
+  -o, --output string                    Output directory (defaults to current directory)
+      --platform string                  Platform to build the image for (default "linux/amd64")
+  -x, --squash-compression stringArray   cmd options for compression to pass to mksquashfs. Full cmd including --comp as the whole values will be passed to mksquashfs. For a full list of options please check mksquashfs manual. (default value: '-comp xz -Xbcj ARCH')
+      --squash-no-compression            Disable squashfs compression. Overrides any values on squash-compression
+  -t, --type string                      Type of image to create (default "raw")
+      --unprivileged                     Makes a build runnable within a non-privileged container, avoids mounting filesystems (experimental)
+
+Global Flags:
+      --config-dir string   Set config dir
+      --debug               Enable debug output
+      --logfile string      Set logfile
+      --quiet               Do not output to stdout
 ```
-
-QEMU supports a wide range of formats including common ones such as `vdi`, `vmdk` or `vhdx`.
-
-The result can be easily tested on QEMU with:
-
-```bash
-> qemu -m 4096 -hda disk.qcow2 -bios /usr/share/qemu/ovmf-x86_64.bin
-```
-
-Note the firmware image path varies depending on the host distro, the path provided in this example is based on openSUSE Leap.