Second pass

Author: alexiri

README.md

@@ -6,64 +6,86 @@ Welcome to your brand-new Atomic AlmaLinux Respin!
 
 ### Set basic configuration
 
-In the ["Build image"](.github/workflows/build.yml) and ["Build ISOs"](.github/workflows/build-iso.yml) jobs, you'll
-find a `set-env` job where you can configure several things:
+In the ["Build image"](.github/workflows/build.yml) and ["Build ISOs"](.github/workflows/build-iso.yml) workflows, you'll find a `set-env` job where you can configure several key variables:
 
-- `REGISTRY`: the registry to push your image to
-- `REGISTRY_USER`: your username for this registry
-- `IMAGE_PATH`: the path to your image
-- `IMAGE_NAME`: your image's name
-- `PLATFORMS`: a comma-separated list of platforms for which to build your image, like `"amd64,arm64"`
+- `REGISTRY`: The container registry to push your image to (default: GitHub Container Registry `ghcr.io`).
+- `REGISTRY_USER`: Your username for the registry.
+- `IMAGE_PATH`: The path/namespace for your image.
+- `IMAGE_NAME`: The name of your image.
+- `PLATFORMS`: A quoted, comma-separated list of platforms to build for (e.g., `"amd64,arm64"`).
 
-If your registry is not Github (ie. `ghcr.io`) or you need a specific token to authenticate
-to your registry, search those two jobs for the line `REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}`
-and replace the token for the appropriate secret.
+If your registry is not GitHub or you need a specific token, search for `REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}` in the workflow files and replace it with the appropriate secret.
 
 ### Pick a base desktop image
 
-By default, this template configures the base image `quay.io/almalinuxorg/atomic-desktop-gnome:10`,
-which is [maintained](https://github.com/AlmaLinux/atomic-desktop) by the [AlmaLinux Atomic SIG](https://wiki.almalinux.org/sigs/Atomic.html).
-If you're not a fan of Gnome, you could also pick our KDE image (`quay.io/almalinuxorg/atomic-desktop-kde:10`).
+By default, this template uses the base image `quay.io/almalinuxorg/atomic-desktop-gnome:10`, maintained by the [AlmaLinux Atomic SIG](https://wiki.almalinux.org/sigs/Atomic.html). If you prefer KDE, you can use `quay.io/almalinuxorg/atomic-desktop-kde:10` instead.
 
-If you'd like to switch images, change the `FROM` line in the [Dockerfile](Dockerfile).
-If you switch to an entirely new key, note that you will also have to download a new Cosign public
-key for this image and specify it's name in the `upstream-public-key` configuration
-parameter of `/.github/workflows/build.yml`, or remove that parameter altogether to
-disable key verification.
+To switch images, change the `FROM` line in the [Dockerfile](Dockerfile). If your image use a different signing key, download the new Cosign public key and specify its name in the `upstream-public-key` parameter in `.github/workflows/build.yml`, or remove the parameter to disable key verification.
 
 ### Setting up Cosign (Optional)
 
-If you'd like to sign your images using Cosign, here's what you need to do:
+If you'd like to sign your images using Cosign:
 
 1. Generate a cosign key:
-    `podman run --rm -it -v /tmp:/cosign-keys bitnami/cosign generate-key-pair`
-    Hit enter when asked for a private key password (that is, don't set a password). Once complete, you'll find the new key in `/tmp/cosign.{key,pub}` on your machine.
-
-2. Add `cosign.pub` to this repository as `/cosign.pub`, commit and push. Feel free to publish this file in other places too, it will be needed by everyone to verify the signature of the published images.
-
-3. In the github repo settings, go to "Secrets and variables" in the "Security" subsection and click on "Actions". Create a new Repository secret called `SIGNING_SECRET` and paste the contents of `cosign.key`. Save `cosign.key` in a secure location and delete it from your /tmp directory.
+   ```sh
+   podman run --rm -it -v /tmp:/cosign-keys bitnami/cosign generate-key-pair
+   ```
+   Leave the password blank. The keys will be in `/tmp/cosign.{key,pub}`.
+2. Add `cosign.pub` to the repository as `/cosign.pub`, commit, and push. This file is public and needed for signature verification.
+3. In GitHub repo settings, go to "Secrets and variables" > "Actions". Create a secret called `SIGNING_SECRET` and paste the contents of `cosign.key`. Store `cosign.key` securely and delete it from `/tmp`.
 
 ## Customizing your respin
 
-Now that you're all set up, it's time for the fun part!
+Now you're ready to make your respin your own!
 
 ### Adding files
 
-Any files you place in [`/files/system/`](files/system/) will be added to your image as is,
-preserving directory structure and file permissions. This is a simple mechanism for adding
-themes, backgrounds, etc.
+Place any files you want to include in your image in [`/files/system/`](files/system/). The directory structure and permissions will be preserved. This is ideal for adding themes, backgrounds, configuration files, etc.
 
 ### Executing commands
 
-In [`/files/scripts/`](files/scripts/), you'll find a series of scripts that will be run
-during image creation. The `build.sh` script will first copy all the files from `/files/system/`
-into the image, then run the scripts in order, and finally run `cleanup.sh`. You can start by modifying [`10-base.sh`](files/scripts/10-base.sh)
-to suit your needs, and add more scripts as needed (always with the naming scheme `XX-whatever.sh`, where XX is a number).
+Scripts in [`/files/scripts/`](files/scripts/) are run during image creation. The `build.sh` script copies files from `/files/system/` into the image, then runs all scripts in order, and finally runs `cleanup.sh`.
 
-Do not modify `build.sh`, `cleanup.sh`, `90-signing.sh` or `91-image-info.sh` unless you
-understand what you're doing, those scripts should not need any customization under normal circumstances.
+- Start by editing [`10-base.sh`](files/scripts/10-base.sh) to suit your needs.
+- Add more scripts as needed, using the naming scheme `XX-whatever.sh` (where `XX` is a number).
+- Do **not** modify `build.sh`, `cleanup.sh`, `90-signing.sh`, or `91-image-info.sh` unless you know what you're doing.
 
 ### Build your new image
 
-Once you've added your files and scripts, commit your changes to let the CI build a new
-image for you. You can also run `make image` on your machine to build the image locally.
+After adding your files and scripts, commit your changes. The CI will build a new image for you automatically. You can also build locally:
+
+```sh
+make image
+```
+
+#### Local development with Makefile
+
+The provided `Makefile` includes several useful commands for local development and testing:
+
+- `make image`: Build the container image using Podman.
+- `make clean`: Remove the `./output` directory and build artifacts.
+- `make iso`: Build a bootable ISO image using [bootc-image-builder](https://github.com/osbuild/bootc-image-builder).
+- `make qcow2`: Build a QCOW2 disk image using bootc-image-builder.
+- `make run-qemu-iso`: Boot the generated ISO in QEMU for testing. Creates a virtual disk if needed.
+- `make run-qemu-qcow`: Boot the generated QCOW2 disk image in QEMU for testing.
+- `make run-qemu`: Boot the raw disk image in QEMU (after installation).
+
+> **Note:** You may need `sudo` privileges and Podman installed. For more details, see the `Makefile`.
+
+## Continuous Integration (CI)
+
+This template is set up with GitHub Actions workflows to build, test, and (optionally) sign your images automatically on every push or pull request. See the `.github/workflows/` directory for details.
+
+## Troubleshooting
+
+- **Build fails locally:** Ensure you have Podman and QEMU installed, and that you have the necessary permissions (try running with `sudo`).
+- **CI build fails:** Check the Actions tab in GitHub for logs. Make sure your secrets and configuration are correct.
+- **Image doesn't boot in QEMU:** Double-check your custom scripts and added files for errors.
+
+## Resources
+
+- [AlmaLinux Atomic SIG](https://wiki.almalinux.org/sigs/Atomic.html)
+- [AlmaLinux Atomic Desktop Images](https://github.com/AlmaLinux/atomic-desktop)
+- [bootc-image-builder](https://github.com/osbuild/bootc-image-builder)
+- [Podman documentation](https://podman.io/)
+- [QEMU documentation](https://www.qemu.org/)