doc: add a guide on getting started using configuration files

README.adoc

@@ -28,7 +28,7 @@ sudo rpi-imager --cli ./work/image-deb12-arm64-min/deb12-arm64-min.img /dev/mmcb
 
 To install via other means, for example using https://github.com/raspberrypi/usbboot[rpiboot,window=_blank] with https://github.com/raspberrypi/pi-gen-micro[pi-gen-micro,window=_blank]'s usb mass-storage or fastboot gadget, or provisioning with https://github.com/raspberrypi/rpi-sb-provisioner[rpi-sb-provisioner,window=_blank], take a look at the documentation in those repositories.
 
-The rpi-image-gen link:./docs/index.adoc[technical documentation] and link:./examples[examples directory] provide customisation and usage guidance.
+The rpi-image-gen link:./getting_started.adoc[getting started guide], link:./docs/index.adoc[technical documentation] and link:./examples[examples directory] provide customisation and usage guidance.
 
 == Why use this?
 

getting_started.adoc

@@ -0,0 +1,119 @@
+= Getting Started
+
+This guide aims to get you started on building your own custom image using `rpi-image-gen` configs, without yet defining your own layers.
+
+== Requirements
+
+* The build environment needs 2GB RAM or more for tmpfs
+- RPi4 or later if building on RPi
+- Building with foreign dpkg operation support on a workstation or build server
+* The build environment needs 4GB storage or more for build artefacts and images
+- 8GB SD card is the absolute minimum when building on RPi, but larger is needed for bigger images
+* The build target can be any Raspberry Pi, but all features are available only on RPi4 or later
+- When building for older targets, some layers will not work
+
+== Building on Ubuntu or Debian amd64
+
+While not officially supported, cross building works well on a recent Debian or Ubuntu amd64. In lieu of the quick start, use the following:
+
+[,sh]
+----
+sudo apt-get -q -y --no-install-recommends install binfmt-support qemu-user-static debian-archive-keyring git
+git clone https://github.com/raspberrypi/rpi-image-gen.git
+cd rpi-image-gen
+sudo ./install_deps.sh
+----
+
+This will:
+
+* Install foreign dpkg operation support and further host dependencies
+* Install Debian keyring from package on Ubuntu
+
+== Define Your Image
+
+We will build three images starting with a single image for a single device. Then we use includes to show how you can define multiple images to manage your whole landscape. In this example, we will assume you have various RPi generations deployed across different locations serving as simple SSH servers on wifi.
+
+=== Project Setup
+
+Let's set up a simple project that includes a configuration file and a script to run installation.
+
+[,sh]
+----
+mkdir -p myproject/bdebstrap
+echo -e 'ClientAliveInterval 60' > myproject/sshdkeepalive.conf
+echo -e '#!/bin/bash\n\nset -eu\n\nchroot $1 sh -c "apt-get -y install network-manager"\ncp ../sshdkeepalive.conf $1/etc/sshd_config.d/\nchroot $1 sh -c "nmcli --offline connection add type wifi ssid $SSID wifi-sec.psk $PSK wifi-sec.key-mgmt wpa-psk autoconnect yes > /etc/NetworkManager/system-connections/$SSID.nmconnection"\nchroot $1 sh -c "chmod 600 /etc/NetworkManager/system-connections/$SSID.nmconnection"' > myproject/bdebstrap/customize90-myscript
+chmod 755 myproject/bdebstrap/customize90-myscript
+----
+
+=== A Simple Base Configuration
+
+Now create the base config file called `myimage.yaml` in `myproject` with the following content:
+
+[,yaml]
+----
+device:
+  user1: myuser
+  user1pass: Fo0bar!!
+  layer: rpi5
+
+image:
+  layer: image-rpios
+  boot_part_size: 128M
+  root_part_size: 1536M
+
+ssh:
+  pubkey_user1: $(cat ${HOME}/.ssh/id_rsa.pub)
+  pubkey_only: y
+
+packages:
+  - wpasupplicant
+
+env:
+  SSID: default
+  PSK: 12345678
+----
+
+Ensure you have an SSH key on the build host, or remove the pubkey_user1 line. Go ahead and build using the instructions below. This will already produce a bootable image, and the config will serve a shared base.
+
+=== Adding Image Identities
+
+Create a file called `myimage-location1.yaml` in `myproject` with the following content:
+
+[,yaml]
+----
+include:
+  file: myimage.yaml
+
+device:
+  hostname: location1
+
+env:
+  SSID: localssid
+  PSK: localpsk
+----
+
+This will define an image with a hostname specific to the location and override the wifi configuration. Again, you can build this and it will work if your device happens to be the same as in the main yaml.
+
+=== Adding Device Specifications
+
+Create a file called `myimage-location1-rpi3.yaml` in `myproject` with the following content:
+
+[,yaml]
+----
+include:
+  file: myimage-location1.yaml
+
+device:
+  layer: rpi3
+----
+
+Building this will produce the specific image for the device you are deploying to location1 at the time. Here we override the rpi5 default.
+
+== Build Your Image
+
+Once your image configuration is ready, you can build everything with specifying just one configuration file. `customize90-myscript` will be automatically included based on its name, executability and location in relation to the `-S` source directory flag. Change `myimage.yaml` to `myimage-location1.yaml` and `myimage-location1-rpi3.yaml` to build the more specific images.
+
+[,sh]
+----
+./rpi-image-gen build -S myproject/ -c myproject/myimage.yaml
+----