Skip to content

Commit

Permalink
docs: fix: issues in docs about modules, create-ublue-image (#147)
Browse files Browse the repository at this point in the history
* fix: clear up some issues in docs abt modules
- better distinction between modules and module configuration
- example for module configuration external from recipe.yml

* chore: create-ublue-image -> general mention
  • Loading branch information
xynydev authored Sep 18, 2023
1 parent 44fb925 commit 9c8e1e2
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 8 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Don't worry, it only requires some basic knowledge about using the terminal and
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.
> Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used one of the automatic repository setup tools in which case the previous repo identifier should already be your repo's details.
> **Warning**
> To start, you *must* create a branch called `live` which is exclusively for your customizations. That is the **only** branch the GitHub workflow will deploy to your container registry. Don't make any changes to the original "template" branch. It should remain untouched. By using this branch structure, you ensure a clear separation between your own "published image" branch, your development branches, and the original upstream "template" branch. Periodically sync and fast-forward the upstream "template" branch to the most recent revision. Then, simply rebase your `live` branch onto the updated template to effortlessly incorporate the latest improvements into your own repository, without the need for any messy, manual "merge commits".
Expand Down
23 changes: 17 additions & 6 deletions config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,16 +16,27 @@ At the top of the recipe, there are four *mandatory* configuration options.

## Modules

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.
The core of startingpoint's configuration is built around the idea of modules. Modules are scripts in the [`../modules`](../modules/) directory that you configure under `modules:` in the recipe. They are executed in order, and can run arbitrary shell commands and write any files.

This repository fetches some useful default modules from [`ublue-os/bling`](https://github.com/ublue-os/bling/), 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 a comprehensive list of modules and their in-depth documentation, check out [the modules page on the website](https://universal-blue.org/tinker/modules/).
This repository fetches some useful default modules from [`ublue-os/bling`](https://github.com/ublue-os/bling/), like [`rpm-ostree`](https://universal-blue.org/tinker/modules/rpm-ostree) for pseudo-declarative package management, [`bling`](https://universal-blue.org/tinker/modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](https://universal-blue.org/tinker/modules/files) for copying files from the `config/files/` directory into your image.

### Including modules from other files and building multiple images
For a comprehensive list of modules, their in-depth documentation and example configuration, check out [the Modules page on the website](https://universal-blue.org/tinker/modules/).

### Building multiple images and including module configuration from other files and

To build multiple images, you need to create another recipe.yml file, which you should name based on what kind of image you want it to build. Then, edit the [`build.yml`](../.github/workflows/build.yml) file. Inside the file, under `jobs: strategy: matrix:`, there's a list of recipe files to build images, which you need to add your new recipe file to. These should be paths to files inside the `config` directory.

Module configuration can be included from other files using the `from-file` syntax. The valye should be a path to a file inside the `config` directory. For example, the following snippet could be used to include the configuration for installing a set of packages common to multiple images.
```yml
Module configuration can be included from other files using the `from-file` syntax. The value should be a path to a file inside the `config` directory. For example, the following snippet could be used to include the configuration for installing a set of packages common to multiple images.
```yaml
modules:
- from-file: common-packages.yml
```
```
And inside config/common-packages.yml
```yaml
type: rpm-ostree
install:
- i3
- dunst
- rofi
- kitty
```
2 changes: 1 addition & 1 deletion config/recipe.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ 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, executed in order
# module configuration, executed in order
# you can include multiple instances of the same module
modules:

Expand Down

0 comments on commit 9c8e1e2

Please sign in to comment.