including builder_example in docs/

.dockerignore

@@ -0,0 +1 @@
+docs

docs/example/.gitignore

@@ -0,0 +1 @@
+.build

docs/example/README.md

@@ -0,0 +1,9 @@
+# Builder Example 
+
+This is a basic example of utilizing the *Garden Linux Builder*.
+
+To build this example run
+
+    ./build base
+
+

docs/example/build

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+
+set -eufo pipefail
+
+container_image=ghcr.io/gardenlinux/builder:5d05982bf4132b0d7814080ea3042344d500adc3
+container_engine=podman
+
+container_run_opts=(
+	--security-opt seccomp=unconfined
+	--security-opt apparmor=unconfined
+	--security-opt label=disable
+	--read-only
+)
+
+container_mount_opts=(
+	-v "$PWD/features:/builder/features:ro"
+	-v "$PWD/keyring.gpg:/builder/keyring.gpg:ro"
+	-v "$PWD/.build:/builder/.build"
+)
+
+use_kms=0
+resolve_cname=0
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+		--container-image)
+			container_image="$2"
+			shift 2
+			;;
+		--container-engine)
+			container_engine="$2"
+			shift 2
+			;;
+		--container-run-opts)
+			declare -a "container_run_opts=($2)"
+			shift 2
+			;;
+		--kms)
+			use_kms=1
+			shift
+			;;
+		--print-container-image)
+			printf '%s\n' "$container_image"
+			exit 0
+			;;
+		--resolve-cname)
+			resolve_cname=1
+			shift
+			;;
+		*)
+			break
+			;;
+	esac
+done
+
+if [ "$container_image" = localhost/builder ]; then
+	dir="$(dirname -- "$(realpath -- "${BASH_SOURCE[0]}")")"
+	"$container_engine" build -t "$container_image" "$dir"
+fi
+
+repo="$(./get_repo)"
+commit="$(./get_commit)"
+timestamp="$(./get_timestamp)"
+default_version="$(./get_version)"
+
+[ -d .build ] || mkdir .build
+
+if [ "$resolve_cname" = 1 ]; then
+	arch="$("$container_engine" run --rm "${container_run_opts[@]}" "${container_mount_opts[@]}" "$container_image" dpkg --print-architecture)"
+	cname="$("$container_engine" run --rm "${container_run_opts[@]}" "${container_mount_opts[@]}" "$container_image" /builder/parse_features --feature-dir /builder/features --default-arch "$arch" --default-version "$default_version" --cname "$1")"
+	short_commit="$(head -c 8 <<< "$commit")"
+	echo "$cname-$short_commit"
+	exit 0
+fi
+
+make_opts=(
+	REPO="$repo"
+	COMMIT="$commit"
+	TIMESTAMP="$timestamp"
+	DEFAULT_VERSION="$default_version"
+)
+
+if [ "$use_kms" = 1 ]; then
+	for e in AWS_DEFAULT_REGION AWS_REGION AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN; do
+		if [ -n "${!e-}" ]; then
+			make_opts+=("$e=${!e}")
+		fi
+	done
+fi
+
+if [ -d cert ]; then
+	container_mount_opts+=(-v "$PWD/cert:/builder/cert:ro")
+fi
+
+"$container_engine" run --rm "${container_run_opts[@]}" "${container_mount_opts[@]}" "$container_image" make --no-print-directory -C /builder "${make_opts[@]}" "$@"

docs/example/features/base/exec.config

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+systemctl enable systemd-networkd
+systemctl enable systemd-resolved

docs/example/features/base/exec.late

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+mkdir -p /etc/kernel
+echo "root=LABEL=ROOT ro" > /etc/kernel/cmdline
+
+mkdir -p /boot/efi/Default
+
+kernel="$(find /boot -name 'vmlinuz-*' | sort -V | tail -n 1)"
+version="${kernel#*-}"
+
+unshare --mount bash -c 'mount -t tmpfs none /sys && mount --bind /usr/bin/false /usr/bin/systemd-detect-virt && "$@"' \
+DRACUT_COMPRESS_XZ="$(command -v xz)" dracut \
+--no-hostonly \
+--force \
+--kver "$version" \
+--modules "bash dash systemd systemd-initrd kernel-modules kernel-modules-extra terminfo udev-rules dracut-systemd base fs-lib shutdown" \
+--reproducible \
+"/boot/initrd.img-$version"
+
+kernel-install add "$version" "$kernel"
+
+sed 's/boot\/efi\///' -i /boot/efi/loader/entries/*.conf
+
+SYSTEMD_ESP_PATH=/boot/efi bootctl --no-variables install

docs/example/features/base/file.include/etc/systemd/network/99-default.network

@@ -0,0 +1,5 @@
+[Match]
+Name=en* eth*
+
+[Network]
+DHCP=yes

docs/example/features/base/file.include/etc/systemd/system/serial-getty@.service.d/autologin.conf

@@ -0,0 +1,3 @@
+[Service]
+ExecStart=
+ExecStart=-/sbin/agetty --autologin root -o '-p -f -- \\u' --keep-baud 115200,38400,9600 %I $TERM

docs/example/features/base/fstab

@@ -0,0 +1,3 @@
+# <file system>    <dir>        <type>    <options>                                <makeimg args>
+LABEL=EFI          /boot/efi    vfat      umask=0077                               type=uefi
+LABEL=ROOT         /            ext4      rw,errors=remount-ro,prjquota,discard

docs/example/features/base/info.yaml

@@ -0,0 +1,2 @@
+description: base
+type: platform

docs/example/features/base/pkg.include

@@ -0,0 +1,6 @@
+dracut
+iproute2
+linux-image-$arch
+systemd
+systemd-boot
+systemd-resolved

docs/example/get_commit

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -eufo pipefail
+
+dir="$(dirname "${BASH_SOURCE[0]}")"
+cd "$dir"
+[ -z "$(git status --porcelain 2> /dev/null)" ] && git rev-parse HEAD 2> /dev/null || echo local

docs/example/get_repo

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -eufo pipefail
+
+echo "http://deb.debian.org/debian"

docs/example/get_timestamp

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -eufo pipefail
+
+echo 0

docs/example/get_version

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -eufo pipefail
+
+echo bookworm