docs: some docs fixes, better formatting, etc

Containerfile

@@ -3,42 +3,39 @@
 # Instead of adding RUN statements here, you should consider creating a script
 # in `config/scripts/`. Read more in `modules/script/README.md`
 
-# It takes in the recipe, version, and base image as arguments,
+# This Containerfile takes in the recipe, version, and base image as arguments,
 # all of which are provided by build.yml when doing builds
 # in the cloud. The ARGs have default values, but changing those
 # does nothing if the image is built in the cloud.
 
+# !! Warning: changing these might not do anything for you. Read comment above.
 ARG IMAGE_MAJOR_VERSION=38
-# Warning: changing this might not do anything for you. Read comment above.
 ARG BASE_IMAGE_URL=ghcr.io/ublue-os/silverblue-main
 
 FROM ${BASE_IMAGE_URL}:${IMAGE_MAJOR_VERSION}
 
-# The default recipe set to the recipe's default filename
+# The default recipe is set to the recipe's default filename
-# so that `podman build` should just work for many people.
+# so that `podman build` should just work for most people.
-ARG RECIPE=recipe.yml
+ARG RECIPE=recipe.yml 
-
 # The default image registry to write to policy.json and cosign.yaml
 ARG IMAGE_REGISTRY=ghcr.io/ublue-os
 
-COPY cosign.pub /usr/share/ublue-os/cosign.pub
 
-COPY config /tmp/config
+COPY cosign.pub /usr/share/ublue-os/cosign.pub
 
 # Copy the bling from ublue-os/bling into tmp, to be installed later by the bling module
 # Feel free to remove these lines if you want to speed up image builds and don't want any bling
 COPY --from=ghcr.io/ublue-os/bling:latest /rpms /tmp/bling/rpms
 COPY --from=ghcr.io/ublue-os/bling:latest /files /tmp/bling/files
 
-# "yq" used in build.sh and the "setup-flatpaks" just-action to read recipe.yml.
+# Copy build scripts & configuration
-# Copied from the official container image since it's not available as an RPM.
-COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq
-
-# Copy build script; this is what parses your recipe
 COPY build.sh /tmp/build.sh
-
-# Copy modules to a temporary directory, they'll only to be executed during the build
 COPY modules /tmp/modules/
+COPY config /tmp/config/
+
+# `yq` is used for parsing the yaml configuration
+# It is copied from the official container image since it's not available as an RPM.
+COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq
 
 # Run the build script, then clean up temp files and finalize container build.
 RUN chmod +x /tmp/build.sh && /tmp/build.sh && \

README.md

@@ -30,12 +30,12 @@ For more information about customization, see [the README in the config director
 
 Documentation around making custom images exists / should be written in two separate places:
 * [The Tinkerer's Guide on the website](https://universal-blue.org/tinker/make-your-own/) for general documentation around making custom images, best practices, tutorials, and so on.
-* Inside this repository for documentation specific to the ins and outs of the template, how it works, how to customize it, and some essential guidance on how to make custom images.
+* Inside this repository for documentation specific to the ins and outs of the template (like module documentation), and just some essential guidance on how to make custom images.
 
 ## Installation
 
 > **Warning**
-> This is an experimental feature and should not be used in production, try it in a VM for a while!
+> [This is an experimental feature](https://www.fedoraproject.org/wiki/Changes/OstreeNativeContainerStable) and should not be used in production, try it in a VM for a while!
 
 To rebase an existing Silverblue/Kinoite installation to the latest build:
 

config/README.md

@@ -4,7 +4,7 @@ The main file of your is *the recipe file*. You can have multiple recipe files,
 
 ## Basic options
 
-At the top of the recipe, there are four mandatory configuration options.
+At the top of the recipe, there are four *mandatory* configuration options.
 
 `name:` is the name of the image that is used when rebasing to it. For example, the name "sapphire" would result in the final URL of the container being `ghcr.io/<yourusername>/sapphire`.
 
@@ -18,7 +18,7 @@ At the top of the recipe, there are four mandatory configuration options.
 
 The core of startingpoint's configuration is built around the idea of modules. Modules are scripts in the [`../modules`](../modules/) directory that you list out under `modules:` in the recipe. They are executed in order, and can run arbitrary shell commands and write any files.
 
-This repository comes with three modules out of the box, [`rpm-ostree`](../modules/rpm-ostree) for pseudo-declarative package management, [`yafti`](../modules/yafti) for installing [yafti](https://github.com/ublue-os/yafti) and easing basic configuration, [`bling`](../modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`script`](../modules/script) for running small custom scripts at the build stage, like pulling in configuration or setting up `rpm-ostree` support for proper signing (see [`signing.sh`](./scripts/signing.sh)).
+This repository comes with some modules out of the box, like [`rpm-ostree`](../modules/rpm-ostree) for pseudo-declarative package management, [`bling`](../modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](../modules/files) for copying files from the `config/files/` directory into your image.
 
 For more in-depth documentation on each module, check out the README.md files in each module folder.
 
@@ -34,17 +34,17 @@ modules:
 
 ### Making modules
 
-If you want to extend startingpoint with custom functionality that requires configuration, you should create a module. Modules are scripts in the subdirectories of the [`../modules`](../modules/) directory. The `type:` key in the recipe.yml should be used as both the name of the folder and script, with the script having an additional `.sh` suffix.
+If you want to extend Startingpoint with custom functionality that requires configuration, you should create a module. Modules are scripts in the subdirectories of the [`../modules`](../modules/) directory. The `type:` key in the recipe.yml should be used as both the name of the folder and script, with the script having an additional `.sh` suffix.
 
 Each module intended for public usage should include a `README.md` file inside it's directory with a short description of the module and documentation for each configuration option.
 
 Modules get only the configuration options given to them in the recipe.yml, not the configuration of other modules or any top-level keys. The configuration is given as the first argument as a single-line json string. You can check out the default modules for examples on how to parse such string using `yq` or `jq`.  
 
-Additionally, each module has access to four environment variables, `CONFIG_DIRECTORY` pointing to the startingpoint directory in `/usr/share/ublue-os/`, `IMAGE_NAME` being the name of the image as declared in the recipe, `BASE_IMAGE` being the URL of the container image used as the base (FROM) in the image, and `OS_VERSION` being the `VERSION_ID` from `/usr/lib/os-release`.
+Additionally, each module has access to four environment variables, `CONFIG_DIRECTORY` pointing to the Startingpoint directory in `/usr/share/ublue-os/`, `IMAGE_NAME` being the name of the image as declared in the recipe, `BASE_IMAGE` being the URL of the container image used as the base (FROM) in the image, and `OS_VERSION` being the `VERSION_ID` from `/usr/lib/os-release`.
 
-A helper bash function called `get_yaml_array` is exported from the main build script. Syntax:
+A helper bash function called `get_yaml_array` is exported from the main build script.
 ```bash
-# "$1" read from the first cli argument, being the module configuration.
+# "$1" is the first cli argument, being the module configuration.
 # If you need to read from some other JSON string, just replace "$1" with "$VARNAME".
 get_yaml_array OUTPUT_VAR_NAME '.yq.key.to.array[]' "$1"
 for THING in "${OUTPUT_VAR_NAME[@]}"; do

config/recipe.yml

@@ -7,21 +7,16 @@ description: A starting point for further customization of uBlue images. Make yo
 base-image: ghcr.io/ublue-os/silverblue-main
 image-version: 38 # latest is also supported if you want new updates ASAP
 
-# list of modules that will be executed in order
+# list of modules, executed in order
-
+# you can include multiple instancesof the same module
-# you can include multiple of the same module
-
 modules:
+
   - type: files
     files:
-      - usr: /usr
+      - usr: /usr # copy static configurations
-  # Copy static configurations and component files.
+                  # configuration you wish to end up in /etc/ on the booted system should be 
-  # Warning: If you want to place anything in "/etc" of the final image, you MUST
+                  # added into /usr/etc/ as that is the proper "distro" config directory on ostree
-  # place them in "./usr/etc" in your repo, so that they're written to "/usr/etc"
+                  # read more in the files module's README
-  # on the final system. That is the proper directory for "system" configuration
-  # templates on immutable Fedora distros, whereas the normal "/etc" is ONLY meant
-  # for manual overrides and editing by the machine's admin AFTER installation!
-  # See issue #28 (https://github.com/ublue-os/startingpoint/issues/28).
 
   - type: rpm-ostree
     repos:
@@ -47,11 +42,10 @@ modules:
 
   - type: yafti # if included, https://github.com/ublue-os/yafti will be installed and set up
     custom-flatpaks: # this section is optional
-      - Celluloid: io.github.celluloid_player.Celluloid
+      # - Celluloid: io.github.celluloid_player.Celluloid
-      - Krita: org.kde.krita
+      # - Krita: org.kde.krita
 
   - type: script
     scripts:
       # this sets up the proper policy & signing files for signed images to work
       - signing.sh
-

modules/README.md

@@ -0,0 +1,3 @@
+# Modules
+
+This directory includes all the different modules for Startingpoint. Refer to the README files inside each module's corresponding directory for in-depth documentation, and the README inside `config/` for more general documentation.

modules/files/README.md

@@ -3,7 +3,7 @@
 The `files` module simplifies the process of copying files to the image during the build time. These files are sourced from the `config/files` directory, which is located at `/tmp/config/files` inside the image.
 
 > **Warning**
-> If you want to place anything in `/etc` of the final image, you MUST place them in `/usr/etc` in your repo, so that they're written to `/usr/etc` on the final system. That is the proper directory for "system" configuration templates on immutable Fedora distros, whereas the normal `/etc` is ONLY meant for manual overrides and editing by the machine's admin AFTER installation! See issue https://github.com/ublue-os/startingpoint/issues/28.
+> If you want to place anything in `/etc` of the final image, you MUST place them in `/usr/etc` in your repo, so that they're written to `/usr/etc` on the final system. That is the proper directory for "system" configuration templates on immutable Fedora distros, whereas the normal `/etc` is meant for manual overrides and editing by the machine's admin AFTER installation! See issue https://github.com/ublue-os/startingpoint/issues/28.
 
 ## Example Configuration: