From c07131b37dd2b1fa9ab6b5eaef7f5b456681de0e Mon Sep 17 00:00:00 2001 From: ER Date: Sun, 13 Aug 2023 18:46:00 +0300 Subject: [PATCH] docs: move & start rewriting configuration docs --- README.md | 68 +++------------------------------------ config/README.md | 19 +++++++++++ config/scripts/autorun.sh | 0 3 files changed, 24 insertions(+), 63 deletions(-) create mode 100644 config/README.md mode change 100644 => 100755 config/scripts/autorun.sh diff --git a/README.md b/README.md index 380aec5..2324e24 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ See the [Make Your Own-page in the documentation](https://universal-blue.org/tin Don't worry, it only requires some basic knowledge about using the terminal and git. +After setup, it is recommended you update this README to describe your custom image. + > **Note** > Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used [`create-ublue-image`](https://github.com/EinoHR/create-ublue-image), in which case the previous repo identifier should already be your repo's details. @@ -20,66 +22,7 @@ Don't worry, it only requires some basic knowledge about using the terminal and ## Customization -The easiest way to start customizing is by looking at and modifying `recipe.yml`. It's documented using comments and should be pretty easy to understand. - -For the base-image field, you can use any other native container image. You will get all the features of that image, plus the ones added here! Check out the [uBlue images list](https://universal-blue.org/images/) to decide what to use! - -If you want to add custom configuration files, you can just add them in the `usr/etc/` directory, which is the official OSTree "configuration template" directory. If you need to add other directories, you can look at the Containerfile to see how it's done. Writing to `/etc` or `/var` in Fedora's immutable OSTree-based distros *isn't supported* and will not work, as those are user-managed locations! - -> **Note** -> The configuration files you put in `/usr/etc/` will automatically be applied to your local `/etc/` by `systemd` whenever you rebase an OSTree system or update the image. If a config file in `/etc/` has been *modified* (compared to the same deployment's defaults), then OSTree [won't overwrite it](https://github.com/ostreedev/ostree/blob/16cb47489e582da9c139fee20acdac7079867843/docs/atomic-upgrades.md?plain=1#L76), but the new version will be available in `/usr/etc/`. Run `sudo ostree admin config-diff` to see the difference between `/etc/` and `/usr/etc/` (`man ostree-admin-config-diff` for further documentation). - -### Custom build scripts - -If you want to execute custom shell scripts or commands in the image build, you shouldn't edit the `scripts/build.sh` or the `Containerfile` directly. - -Instead, you should create your own custom shell scripts in the `scripts/` directory (look at the `example.sh`). After creating your scripts, enable them in the `scripts:` section of your `recipe.yml`, within the specific "build stage" category where the scripts are intended to be executed. Alternatively, enable the `autorun.sh` helper script in your recipe to automatically execute your custom scripts. - -Read [the README in the `scripts/` directory](https://github.com/ublue-os/startingpoint/blob/main/scripts/README.md) for more information. - -### Custom package repositories - -If you want to add custom package repositories to your image, you can include them in the `recipe.yml` as a list of URLs under the `rpm.repos:` section. They **must** be proper `.repo` files (such as `https://copr.fedorainfracloud.org/coprs/atim/starship/repo/fedora-38/atim-starship-fedora-38.repo`). In the build process, the `.repo` file will be downloaded and placed inside `/etc/yum.repos.d/` where rpm-ostree can access it. - -You can use this to add [COPR repositories](https://copr.fedorainfracloud.org/) to your image. -COPR is like the Arch User Repository for Fedora, where you can find extra packages that wouldn't otherwise be available. The repositories are community-created, so use them at your own risk. [Read more](https://docs.pagure.org/copr.copr/user_documentation.html) - -Tip: You can use the magic string `%FEDORA_VERSION%` in your repo URLs, to automatically refer to the correct repository for your current Fedora version. - -If your `.repo` file is not available as a hosted URL and you need to copy it manually, you can upload the file in your github repository or a gist and add the raw link to the file under `rpm.repos:`. Another option in this scenario would be to create a folder for `.repo` files in your repository and add `COPY repos /etc/yum.repos.d/` in the `Containerfile`. - -### Building multiple images - -You can build multiple images using multiple `recipe.yml` files. They will share the Containerfile and everything else, but things like packages declared in the recipe will be different between the images. For a more robust multibuild setup, you could consider forking from the [ublue-os/main](https://github.com/ublue-os/main/) repo, which was built from the purpose. - -In order to build multiple recipes, you need to declare each one below line ~33 in `build.yml`. The files should be in the root of the repository. - -Example: Adding a new recipe called `recipe-2.yml` (snippets from the `matrix` section of `build.yml`) - -Before: - -```yml -matrix: - recipe: - - recipe.yml -``` - -After: - -```yml -matrix: - recipe: - - recipe.yml - - recipe-2.yml -``` - -### [yafti](https://github.com/ublue-os/yafti/) - -`yafti` is the uBlue "first boot" installer. It shows up the first time a user logs into uBlue. By default, the menu also shows up again anytime the image's yafti configuration differs from the user's last encounter, so feel free to expand or modify your custom image's yafti configuration over time. Your users will then see the yafti menu again after the OS update, and will be given a chance to install any new additions. - -Its configuration can be found in `/usr/share/ublue-os/firstboot/yafti.yml` of the installed OS. It includes an optional selection of Flatpaks to install, along with a new group that's automatically added for all Flatpaks declared in `recipe.yml`. You can look at what's done in the `yafti.yml` config and modify it to your liking (in the repository, before building the image, since the installed system file is immutable). - -If you want to completely disable yafti, simply set the recipe's `firstboot.yafti` flag to `false`, which then removes all yafti-related files and configurations from your final image. The files in `usr/share/ublue-os/firstboot/` are responsible for automatically running yafti at login, and they will *only* be bundled in your image if `yafti` is enabled in your recipe! +For information about customization, see [the README in the config directory](config/README.md) ## Installation @@ -88,7 +31,7 @@ If you want to completely disable yafti, simply set the recipe's `firstboot.yaft To rebase an existing Silverblue/Kinoite installation to the latest build: -- First rebase to the image unsigned, to get the proper signing keys and policies installed: +- First rebase to the unsigned image, to get the proper signing keys and policies installed: ``` sudo rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/startingpoint:latest ``` @@ -105,14 +48,13 @@ To rebase an existing Silverblue/Kinoite installation to the latest build: systemctl reboot ``` - This repository builds date tags as well, so if you want to rebase to a particular day's build: ``` sudo rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/startingpoint:20230403 ``` -This repository by default also supports signing +This repository by default also supports signing. The `latest` tag will automatically point to the latest build. That build will still always use the Fedora version specified in `recipe.yml`, so you won't get accidentally updated to the next major version. diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..fff821e --- /dev/null +++ b/config/README.md @@ -0,0 +1,19 @@ +# Configuring your image + +The main file of your is *the recipe file*. You can have multiple recipe files, and the ones to build are declared in the matrix section of [build.yml](../.github/workflows/build.yml). + +## Basic 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//sapphire`. + +`description:` is a short description of your image that will be attached to your image's metadata. + +`base-image:` is the URL of the image your image will be built upon. + +`image-version:` is the version tag of the `base-image` that will be pulled. For example, Universal Blue's images build with Fedora version tags (`38`, `39`), with the `latest` tag for the latest major version, and [many other tags](https://github.com/ublue-os/main/pkgs/container/base-main/versions?filters%5Bversion_type%5D=tagged). + +## Modules + +The core of startingpoint's configuration is built around the idea of modules. To be continued... \ No newline at end of file diff --git a/config/scripts/autorun.sh b/config/scripts/autorun.sh old mode 100644 new mode 100755