82 lines
4.6 KiB
Markdown
82 lines
4.6 KiB
Markdown
# BlueBuild Template
|
|
|
|
This is a constantly updating template repository for creating [a native container image](https://fedoraproject.org/wiki/Changes/OstreeNativeContainerStable) designed to be customized however you want. GitHub will build your image for you, and then host it for you on [ghcr.io](https://github.com/features/packages). You then just tell your computer to boot off of that image. GitHub keeps 90 days worth image backups for you, thanks Microsoft!
|
|
|
|
For more info, check out the [BlueBuild homepage](https://blue-build.org/) and the [BlueBuild CLI](https://github.com/blue-build/cli)
|
|
|
|
## Getting started
|
|
|
|
See the [BlueBuild docs](https://blue-build.org/learn/getting-started) for quick setup instructions for setting up your own repository based on this template.
|
|
|
|
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.
|
|
|
|
## Customization
|
|
|
|
The easiest way to start customizing is by looking at and modifying `config/recipe.yml`. It's documented using comments and should be pretty easy to understand.
|
|
|
|
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 and will be applied to `/etc/` on boot. `config/files/usr` is copied into your image's `/usr` by default. If you need to add other directories in the root of your image, that can be done using the `files` module. Writing to `/var/` in the image builds of OSTree-based distros isn't supported and will not work, as that is a local user-managed directory!
|
|
|
|
For more information about customization, see [the README in the config directory](config/README.md)
|
|
|
|
## Installation
|
|
|
|
> **Warning**
|
|
> [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:
|
|
|
|
- First rebase to the unsigned image, to get the proper signing keys and policies installed:
|
|
```
|
|
rpm-ostree rebase ostree-unverified-registry:ghcr.io/blue-build/template:latest
|
|
```
|
|
- Reboot to complete the rebase:
|
|
```
|
|
systemctl reboot
|
|
```
|
|
- Then rebase to the signed image, like so:
|
|
```
|
|
rpm-ostree rebase ostree-image-signed:docker://ghcr.io/blue-build/template:latest
|
|
```
|
|
- Reboot again to complete the installation
|
|
```
|
|
systemctl reboot
|
|
```
|
|
|
|
This repository builds date tags as well, so if you want to rebase to a particular day's build:
|
|
|
|
```
|
|
rpm-ostree rebase ostree-image-signed:docker://ghcr.io/blue-build/template:20230403
|
|
```
|
|
|
|
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.
|
|
|
|
## ISO
|
|
|
|
This template includes a simple Github Action to build and release an ISO of your image.
|
|
|
|
To run the action, simply edit the `boot_menu.yml` by changing all the references to startingpoint to your repository. This should trigger the action automatically.
|
|
|
|
The Action uses [isogenerator](https://github.com/ublue-os/isogenerator) and works in a similar manner to the official Universal Blue ISO. If you have any issues, you should first check [the documentation page on installation](https://universal-blue.org/installation/). The ISO is a netinstaller and should always pull the latest version of your image.
|
|
|
|
Note that this release-iso action is not a replacement for a full-blown release automation like [release-please](https://github.com/googleapis/release-please).
|
|
|
|
## `just`
|
|
|
|
The [`just`](https://just.systems/) command runner is included in all `ublue-os/main`-derived images.
|
|
|
|
You need to have a `~/.justfile` with the following contents and `just` aliased to `just --unstable` (default in posix-compatible shells on ublue) to get started with just locally.
|
|
```
|
|
!include /usr/share/ublue-os/just/main.just
|
|
!include /usr/share/ublue-os/just/nvidia.just
|
|
!include /usr/share/ublue-os/just/custom.just
|
|
```
|
|
Then type `just` to list the just recipes available.
|
|
|
|
The file `/usr/share/ublue-os/just/custom.just` is intended for the custom just commands (recipes) you wish to include in your image. By default, it includes the justfiles from [`ublue-os/bling`](https://github.com/ublue-os/bling), if you wish to disable that, you need to just remove the line that includes bling.just.
|
|
|
|
See [the just-page in the Universal Blue documentation](https://universal-blue.org/guide/just/) for more information.
|