docs: restructure diataxis and aggreagtion

Signed-off-by: Eike Waldt <waldt@b1-systems.de>
On-behalf-of: SAP <eike.waldt@sap.com>

Author: yeoldegrove

docs/tutorials/getting_started.md docs/how-to/custom-feature.mddocs/tutorials/getting_started.md renamed to docs/how-to/custom-feature.md

@@ -1,20 +1,21 @@
 ---
-title: "Builder - Getting Started"
-github_target_path: "docs/reference/supporting_tools/builder/tutorials/getting_started.md"
+title: "Building a custom Feature"
+description: Create a custom Feature and build an image with the Builder
 migration_status: "new"
 migration_source: ""
 migration_issue: ""
 migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
 migration_approved: false
 github_org: gardenlinux
 github_repo: builder
-github_source_path: docs/tutorials/getting_started.md
+github_source_path: docs/how-to/custom-feature.md
+github_target_path: "docs/how-to/custom-feature.md"
 ---
 
-# Getting Started: Creating a Custom Linux Image with Builder
+# Create a custom Feature and build an image with the Builder
 
-This tutorial will walk you through the process of creating a custom Linux image using the Builder tool.
-We will start with the Builder example repository and build a *feature* to add an [`nginx` HTTP server](https://nginx.org/en/) to our image.
+This How-To will walk you through the process of creating a custom Linux image using the Builder tool.
+We will start with the Builder example repository and build a _feature_ to add an [`nginx` HTTP server](https://nginx.org/en/) to our image.
 
 Let's begin by creating a new GitHub repository based on the Builder example repository using this link:
 
@@ -53,9 +54,9 @@ mkdir features/nginx
 ```
 
 > This is where our nginx feature will live.
-Features are a concept of the builder that allows us to build variants of images.
-For example, if we wanted to add an alternative HTTP server later, we could add an `apacheHttpd` feature.
-At image build time, we could pick if we want the `nginx` or the `apacheHttpd` feature.
+> Features are a concept of the builder that allows us to build variants of images.
+> For example, if we wanted to add an alternative HTTP server later, we could add an `apacheHttpd` feature.
+> At image build time, we could pick if we want the `nginx` or the `apacheHttpd` feature.
 
 2. Create a file named `info.yaml` inside `features/nginx` and edit it with the content below:
 
@@ -68,17 +69,16 @@ features:
 ```
 
 > The `info.yaml` file is required for each feature by the builder.
-We'll specify that our `nginx` feature includes the `base` feature.
-This makes sense because the `nginx` feature on its own does not contain a full operating system, so to get a bootable image we include the debian system as it is defined in `base`.
-See [features documentation](../reference/features.md) for detailed information on the structure of features.
+> We'll specify that our `nginx` feature includes the `base` feature.
+> This makes sense because the `nginx` feature on its own does not contain a full operating system, so to get a bootable image we include the debian system as it is defined in `base`.
+> See [features documentation](../reference/features.md) for detailed information on the structure of features.
 
 1. Create a file named `pkg.include` inside `features/nginx` with the following content:
 
 ```
 nginx
 ```
 
-
 > `pkg.include` is a list of packages this feature needs, each feature on a new line.
 
 4. Create a file named `exec.config` inside `features/nginx` with the following content:
@@ -91,9 +91,8 @@ set -eufo pipefail
 systemctl enable nginx
 ```
 
-
 > `exec.config` is a shell script we can use to customize our image.
-In this case, we [enable the systemd unit for nginx](https://www.freedesktop.org/software/systemd/man/latest/systemctl.html#enable%20UNIT…) which makes nginx start on boot.
+> In this case, we [enable the systemd unit for nginx](https://www.freedesktop.org/software/systemd/man/latest/systemctl.html#enable%20UNIT…) which makes nginx start on boot.
 
 5. Make the `exec.config` file executable:
 
@@ -107,17 +106,16 @@ chmod +x features/nginx/exec.config
 mkdir -p features/nginx/file.include/var/www/html
 ```
 
-
 > The `file.include` directory allows us to merge files and directories into the root filesystem of our image.
 
 7. Create a dummy `index.html` file inside `features/nginx/file.include/var/www/html` with content like the following (or customize it as desired):
 
 ```html
 <!DOCTYPE html>
 <html>
-	<body>
-		<p>Hello World!</p>
-	</body>
+  <body>
+    <p>Hello World!</p>
+  </body>
 </html>
 ```
 
@@ -137,7 +135,7 @@ If everything worked as intended, you should see the system boot up. Once the sy
 
 To also build the new image on GitHub Actions, we'll need to modify the `.github/workflows/build.yml` file.
 
-Let's change the *build* step to include the `nginx` feature we just created, and let's upload our built image to GitHub's artifact storage:
+Let's change the _build_ step to include the `nginx` feature we just created, and let's upload our built image to GitHub's artifact storage:
 
 ```diff
 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -159,3 +157,8 @@ index 181a646..9e4261e 100644
 Now commit and push your changes and GitHub will build the image for you.
 
 Congratulations! You have successfully created your first feature for the Builder and setup a CI Pipeline to build the image. :tada:
+
+## Next Steps
+
+- [Builder](/reference/supporting-tools/builder.md)
+- [Features Reference](/reference/features.md)

docs/overview/README.md

@@ -0,0 +1,87 @@
+---
+title: "Builder"
+description: An overview of the Builder Tool
+migration_status: "new"
+migration_source: ""
+migration_issue: ""
+migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
+migration_approved: false
+github_org: gardenlinux
+github_repo: python-gardenlinux-lib
+github_source_path: docs/overview/index.md
+github_target_path: "docs/reference/supporting_tools/builder.md"
+---
+
+# Builder
+
+## Overview
+
+The Builder is a powerful tool for effortlessly building Linux system images based on config directories. It serves as the primary build tooling for the [gardenlinux](https://github.com/gardenlinux/gardenlinux) project.
+
+By default, the Builder runs inside rootless Podman, enabling building without requiring elevated permissions.
+
+## Requirements
+
+The Builder has minimal dependencies and only requires a working container engine. We recommend using rootless Podman. Please refer to the [Podman rootless setup guide](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md) for instructions on setting it up.
+
+## Usage
+
+To utilize the Builder, follow these steps:
+
+1. Download the latest version of the [build script](https://github.com/gardenlinux/builder/releases/download/latest/build).
+2. Run the build script within a config directory.
+
+```shell
+wget https://github.com/gardenlinux/builder/releases/download/latest/build
+./build ${target}
+```
+
+By default, the Builder uses `podman` as the container engine. If you prefer using a different container engine, you can specify it using the `--container-engine` option.
+
+If you decide to use `docker` on a system restricting unprivileged user namespaces with apparmor (e.g. Ubuntu 23.10 or newer) an apparmor profile allowing `userns` is required. This can be automatically created and selected by the Builder by opting in to the permanent system change. You can avoid this by:
+
+- Using `podman`
+- Passing a custom profile using the `--apparmor-profile` option
+- Using a system not restricting unprivileged user namespaces
+
+## Config Directory
+
+A config directory serves as the input for the Builder and is used to create a Linux system image. It consists of the following components:
+
+- **`features` directory**: Contains sub-directories for each feature. You can create your own features by referring to [features.md](docs/features.md).
+
+- **`cert` directory** (optional): If you plan to use secure boot, include a `cert` directory.
+
+In addition to the above components, your configuration directory must include the following configuration scripts:
+
+- `get_commit`: This script should output the Git commit used to tag the build artifacts.
+- `get_repo`: This script should output the apt package repository to use.
+- `get_timestamp`: This script should output the timestamp to be used instead of the real system time, ensuring reproducibility of builds.
+- `get_version`: This script should output the version of the package repository to use. For example, use `forky` for Debian or `today` for Garden Linux.
+- `keyring.gpg`: The PGP key used to validate the package repository. For Debian, you can obtain this key from the [debian-archive-keyring](https://packages.debian.org/forky/debian-archive-keyring) package.
+
+For a quick start guide on setting up your own config directory with your own features checkout [getting_started.md](docs/getting_started.md).
+
+### Example Config Directory
+
+If you're new to configuring the Builder, you can find a minimal example config directory at [gardenlinux/builder_example](https://github.com/gardenlinux/builder_example). For a more comprehensive example, refer to the main [gardenlinux](https://github.com/gardenlinux/gardenlinux) repository.
+
+Feel free to explore these examples to gain a better understanding of how to effectively structure your own config directory.
+
+## Local Development
+
+To test changes made to the builder locally you can simply create a symlink to the build script inside the builder directory inside a config directory. This will automatically be detected by the build script and the builder re-build iff necessary.
+
+e.g.: if you have the gardenlinux and builder repos both inside the same parent directory and you want to work on the builder you would do the following:
+
+```
+cd gardenlinux
+ln -f -s ../builder/build build
+```
+
+Now you can make your modifications inside the builder directory and running `./build ${target}` inside the gardenlinux repo will use the local builder, rebuilding the build container if necessary.
+
+## Next Steps
+
+- [Features Reference](/reference/features.md)
+- [Building a custom Feature](/how-to/custom-features.md)

docs/references/features.md docs/reference/features.mddocs/references/features.md renamed to docs/reference/features.md

@@ -1,14 +1,15 @@
 ---
-title: "Builder - Features"
-github_target_path: "docs/reference/supporting_tools/builder/reference/features.md"
+title: "Features"
+description: Detailed specification of Features
 migration_status: "new"
 migration_source: ""
 migration_issue: ""
 migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
 migration_approved: false
 github_org: gardenlinux
 github_repo: builder
-github_source_path: docs/references/features.md
+github_source_path: docs/reference/features.md
+github_target_path: docs/reference/features.md
 ---
 
 # Features
@@ -17,15 +18,15 @@ Each feature must contain an `info.yaml` file that adheres to the following stru
 
 ## `info.yaml` file structure:
 
-- `description`: (*optional*) A string explaining the purpose or functionality of the feature.
+- `description`: (_optional_) A string explaining the purpose or functionality of the feature.
 - `type`: Can be one of the following:
   - `platform`
   - `element`
   - `flag`
   - While the builder does not make any technical distinctions between these feature types, it is recommended that each image uses only one `platform`, and `flag` should be used for minor changes without including other features.
-- `features`: (*optional*) A sub-structure that contains related features.
-	- `include`: (*optional*) A list of features that will automatically be included if this feature is selected.
-	- `exclude`: (*optional*) A list of features that are incompatible with this feature. If any of these features were implicitly included from another feature, they will be removed from the feature set. If they were explicitly provided as part of the target, the build will fail.
+- `features`: (_optional_) A sub-structure that contains related features.
+  - `include`: (_optional_) A list of features that will automatically be included if this feature is selected.
+  - `exclude`: (_optional_) A list of features that are incompatible with this feature. If any of these features were implicitly included from another feature, they will be removed from the feature set. If they were explicitly provided as part of the target, the build will fail.
 
 Here's an example of an `info.yaml` file:
 
@@ -128,3 +129,8 @@ They take the image artifact created by an image script and output a different f
 Scripts of the form `convert.<ext>` get the raw image as input and produce a `.<ext>` output.
 Scripts of the form `convert.<extA>~<extB>` get `.<extB>` as input and produces `.<extA>` as output.
 The second form is only useful for advanced use cases, if you are not aware of one, you'll probably never need it!
+
+## Next Steps
+
+- [Builder](/reference/supporting-tools/builder.md)
+- [Building a custom Feature](/how-to/custom-features.md)