diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 292 |
1 files changed, 140 insertions, 152 deletions
@@ -1,163 +1,185 @@ # image-template -# Purpose +This repository is meant to be a template for building your own custom [bootc](https://github.com/bootc-dev/bootc) image. This template is the recommended way to make customizations to any image published by the Universal Blue Project. -This repository is meant to be a template for building your own custom [bootc](https://github.com/bootc-dev/bootc) image. This template is the recommended way to make customizations to any image published by the Universal Blue Project: -- Products: [Aurora](https://getaurora.dev/), [Bazzite](https://bazzite.gg/), [Bluefin](https://projectbluefin.io/), [uCore](https://projectucore.io/) -- Base images: [main](https://github.com/ublue-os/main/) - the product images build on these and may be a better starting point depending on what you want. +# Community -or any other base image if you want to start from scratch: +If you have questions about this template after following the instructions, try the following spaces: +- [Universal Blue Forums](https://universal-blue.discourse.group/) +- [Universal Blue Discord](https://discord.gg/WEu6BdFEtp) +- [bootc discussion forums](https://github.com/bootc-dev/bootc/discussions) - This is not an Universal Blue managed space, but is an excellent resource if you run into issues with building bootc images. -- Fedora: `quay.io/fedora/fedora-bootc:41` -- CentOS Stream 10: `quay.io/centos-bootc/centos-bootc:stream10` +# How to Use -This template includes a Containerfile and a Github workflow for building the container image, signing, and proper metadata to be listed on [artifacthub](https://artifacthub.io/). As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry. +To get started on your first bootc image, simply read and follow the steps in the next few headings. +If you prefer instructions in video form, TesterTech created an excellent tutorial, embedded below. -# Prerequisites +[](https://www.youtube.com/watch?v=IxBl11Zmq5wE) -Working knowledge in the following topics: +## Step 0: Prerequisites -- Containers - - https://www.youtube.com/watch?v=SnSH8Ht3MIc - - https://www.mankier.com/5/Containerfile -- bootc - - https://bootc-dev.github.io/bootc/ -- Fedora Silverblue (and other Fedora Atomic variants) - - https://docs.fedoraproject.org/en-US/fedora-silverblue/ -- Github Workflows - - https://docs.github.com/en/actions/using-workflows +These steps assume you have the following: +- A Github Account +- A machine running a bootc image (e.g. Bazzite, Bluefin, Aurora, or Fedora Atomic) +- Experience installing and using CLI programs -# Video Tutorial +## Step 1: Preparing the Template -TesterTech has made a tutorial video, check it out: +### Step 1a: Copying the Template -[](https://www.youtube.com/watch?v=IxBl11Zmq5wE) +Select `Use this Template` on this page. You can set the name and description of your repository to whatever you would like, but all other settings should be left untouched. -# How to Use +Once you have finished copying the template, you need to enable the Github Actions workflows for your new repository. +To enable the workflows, go to the `Actions` tab of the new repository and click the button to enable workflows. -## Template +### Step 1b: Cloning the New Repository -Select `Use this Template` and create a new repository from it. To enable the workflows, you may need to go the `Actions` tab of the new repository and click to enable workflows. +Here I will defer to the much superior GitHub documentation on the matter. You can use whichever method is easiest. +[GitHub Documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) -## Containerfile +Once you have the repository on your local drive, proceed to the next step. -This file defines the operations used to customize the selected image. It contains examples of possible modifications, including how to: -- change the upstream from which the custom image is derived -- add additional RPM packages -- add binaries as a layer from other images +## Step 2: Initial Setup -## Building disk images +### Step 2a: Creating a Cosign Key -This template provides an out of the box workflow for creating ISO and other disk images for your custom OCI image which can be used to directly install onto your machines. +Container signing is important for end-user security and is enabled on all Universal Blue images. By default the image builds *will fail* if you don't. -This template provides a way to upload the disk images that is generated from the workflow to a S3 bucket or it will be available as an artifact from the job. To upload to S3 we use a tool called [rclone](https://rclone.org/) which is able to use [many S3 providers](https://rclone.org/s3/). For more details on how to configure this see the details [below](#build-isoyml). +First, install the [cosign CLI tool](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-install-cosign/#installing-cosign-with-the-cosign-binary) +With the cosign tool installed, run inside your repo folder: -## Workflows +```bash +cosign generate-key-pair +``` -### build.yml +Do NOT put in a password when it asks you to, just press enter. The signing key will be used in GitHub Actions and will not work if it is encrypted. -This workflow creates your custom OCI image and publishes it to the Github Container Registry (GHCR). By default, the image name will match the Github repository name. +> [!WARNING] +> Be careful to *never* accidentally commit `cosign.key` into your git repo. If this key goes out to the public, the security of your repository is compromised. -### build-disk.yml +Next, you need to add the key to GitHub. This makes use of GitHub's secret signing system. -This workflow creates a disk images from your OCI image by utilizing the [bootc-image-builder](https://osbuild.org/docs/bootc/). In order to use this workflow you must complete the following steps: +<details> + <summary>Using the Github Web Interface (preferred)</summary> -- Modify `disk_config/iso.toml` to point to your custom container image before generating an ISO image. -- If you changed your image name from the default in `build.yml` then in the `build-disk.yml` file edit the `IMAGE_REGISTRY`, `IMAGE_NAME` and `DEFAULT_TAG` environment variables with the correct values. If you did not make changes, skip this step. -- Finally, if you want to upload your disk images to S3 then you will need to add your S3 configuration to the repository's Action secrets. This can be found by going to your repository settings, under `Secrets and Variables` -> `Actions`. You will need to add the following - - `S3_PROVIDER` - Must match one of the values from the [supported list](https://rclone.org/s3/) - - `S3_BUCKET_NAME` - Your unique bucket name - - `S3_ACCESS_KEY_ID` - It is recommended that you make a separate key just for this workflow - - `S3_SECRET_ACCESS_KEY` - See above. - - `S3_REGION` - The region your bucket lives in. If you do not know then set this value to `auto`. - - `S3_ENDPOINT` - This value will be specific to the bucket as well. + Go to your repository settings, under `Secrets and Variables` -> `Actions` +  + Add a new secret and name it `SIGNING_SECRET`, then paste the contents of `cosign.key` into the secret and save it. Make sure it's the .key file and not the .pub file. Once done, it should look like this: +  +</details> +<details> +<summary>Using the Github CLI</summary> -Once the workflow is done, you'll find the disk images either in your S3 bucket or as part of the summary under `Artifacts` after the workflow is completed. +If you have the `github-cli` installed, run: -#### Container Signing +```bash +gh secret set SIGNING_SECRET < cosign.key +``` +</details> -Container signing is important for end-user security and is enabled on all Universal Blue images. It is recommended you set this up, and by default the image builds *will fail* if you don't. +### Step 2b: Choosing Your Base Image -This provides users a method of verifying the image. +To choose a base image, simply modify the line in the container file starting with `FROM`. This will be the image your image derives from, and is your starting point for modifications. +For a base image, you can choose any of the Universal Blue images or start from a Fedora Atomic system. Below this paragraph is a dropdown with a non-exhaustive list of potential base images. -1. Install the [cosign CLI tool](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-install-cosign/#installing-cosign-with-the-cosign-binary) +<details> + <summary>Base Images</summary> -2. Run inside your repo folder: + - Bazzite: `ghcr.io/ublue-os/bazzite:stable` + - Aurora: `ghcr.io/ublue-os/aurora:stable` + - Bluefin: `ghcr.io/ublue-os/bluefin:stable` + - Universal Blue Base: `ghcr.io/ublue-os/base-main:latest` + - Fedora: `quay.io/fedora/fedora-bootc:42` - ```bash - cosign generate-key-pair - ``` + You can find more Universal Blue images on the [packages page](https://github.com/orgs/ublue-os/packages). +</details> - - - Do NOT put in a password when it asks you to, just press enter. The signing key will be used in GitHub Actions and will not work if it is encrypted. +If you don't know which image to pick, choosing the one your system is currently on is the best bet for a smooth transition. To find out what image your system currently uses, run the following command: +```bash +sudo bootc status +``` +This will show you all the info you need to know about your current image. The image you are currently on is displayed after `Booted image:`. Paste that information after the `FROM` statement in the Containerfile to set it as your base image. -> [!WARNING] -> Be careful to *never* accidentally commit `cosign.key` into your git repo. +### Step 2c: Changing Names -3. Add the private key to GitHub +Change the first line in the [Justfile](./Justfile) to your image's name. - - This can also be done manually. Go to your repository settings, under `Secrets and Variables` -> `Actions` -  - Add a new secret and name it `SIGNING_SECRET`, then paste the contents of `cosign.key` into the secret and save it. Make sure it's the .key file and not the .pub file. Once done, it should look like this: -  +To commit and push all the files changed and added in step 2 into your Github repository: +```bash +git add Containerfile Justfile cosign.pub +git commit -m "Initial Setup" +git push +``` +Once pushed, go look at the Actions tab on your Github repository's page. The green checkmark should be showing on the top commit, which means your new image is ready! - - (CLI instructions) If you have the `github-cli` installed, run: +## Step 3: Switch to Your Image - ```bash - gh secret set SIGNING_SECRET < cosign.key - ``` +From your bootc system, run the following command substituting in your Github username and image name where noted. +```bash +sudo bootc switch ghcr.io/<username>/<image_name> +``` +This should queue your image for the next reboot, which you can do immediately after the command finishes. You have officially set up your custom image! See the following section for an explanation of the important parts of the template for customization. -4. Commit the `cosign.pub` file to the root of your git repository. +# Repository Contents -# Community +## Containerfile -- [**bootc discussion forums**](https://github.com/bootc-dev/bootc/discussions) - Nothing in this template is ublue specific, the upstream bootc project has a discussions forum where custom image builders can hang out and ask questions. +The [Containerfile](./Containerfile) defines the operations used to customize the selected image.This file is the entrypoint for your image build, and works exactly like a regular podman Containerfile. For reference, please see the [Podman Documentation](https://docs.podman.io/en/latest/Introduction.html). -## Artifacthub +## build.sh -This template comes with the necessary tooling to index your image on [artifacthub.io](https://artifacthub.io), use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. This is important to you for a few reasons: +The [build.sh](./build_files/build.sh) file is called from your Containerfile. It is the best place to install new packages or make any other customization to your system. There are customization examples contained within it for your perusal. -- The value of artifacthub is it's one place for people to index their custom images, and since we depend on each other to learn, it helps grow the community. -- You get to see your pet project listed with the other cool projects in Cloud Native. -- Since the site puts your README front and center, it's a good way to learn how to write a good README, learn some marketing, finding your audience, etc. +## build.yml -[Discussion thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) +The [build.yml](./.github/workflows/build.yml) Github Actions workflow creates your custom OCI image and publishes it to the Github Container Registry (GHCR). By default, the image name will match the Github repository name. There are several environment variables at the start of the workflow which may be of interest to change. +# Building Disk Images -### Justfile Documentation +This template provides an out of the box workflow for creating disk images (ISO, qcow, raw) for your custom OCI image which can be used to directly install onto your machines. -This `Justfile` contains various commands and configurations for building and managing container images and virtual machine images using Podman and other utilities. +This template provides a way to upload the disk images that is generated from the workflow to a S3 bucket. The disk images will also be available as an artifact from the job, if you wish to use an alternate provider. To upload to S3 we use [rclone](https://rclone.org/) which is able to use [many S3 providers](https://rclone.org/s3/). -#### Environment Variables +## Setting Up ISO Builds -- `image_name`: The name of the image (default: "image-template"). -- `default_tag`: The default tag for the image (default: "latest"). -- `bib_image`: The Bootc Image Builder (BIB) image (default: "quay.io/centos-bootc/bootc-image-builder:latest"). +The [build-disk.yml](./.github/workflows/build-disk.yml) Github Actions workflow creates a disk image from your OCI image by utilizing the [bootc-image-builder](https://osbuild.org/docs/bootc/). In order to use this workflow you must complete the following steps: -#### Aliases +1. Modify `disk_config/iso.toml` to point to your custom container image before generating an ISO image. +2. If you changed your image name from the default in `build.yml` then in the `build-disk.yml` file edit the `IMAGE_REGISTRY`, `IMAGE_NAME` and `DEFAULT_TAG` environment variables with the correct values. If you did not make changes, skip this step. +3. Finally, if you want to upload your disk images to S3 then you will need to add your S3 configuration to the repository's Action secrets. This can be found by going to your repository settings, under `Secrets and Variables` -> `Actions`. You will need to add the following + - `S3_PROVIDER` - Must match one of the values from the [supported list](https://rclone.org/s3/) + - `S3_BUCKET_NAME` - Your unique bucket name + - `S3_ACCESS_KEY_ID` - It is recommended that you make a separate key just for this workflow + - `S3_SECRET_ACCESS_KEY` - See above. + - `S3_REGION` - The region your bucket lives in. If you do not know then set this value to `auto`. + - `S3_ENDPOINT` - This value will be specific to the bucket as well. -- `build-vm`: Alias for `build-qcow2`. -- `rebuild-vm`: Alias for `rebuild-qcow2`. -- `run-vm`: Alias for `run-vm-qcow2`. +Once the workflow is done, you'll find the disk images either in your S3 bucket or as part of the summary under `Artifacts` after the workflow is completed. +# Artifacthub -#### Commands +This template comes with the necessary tooling to index your image on [artifacthub.io](https://artifacthub.io). Use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. This is important to you for a few reasons: -###### `check` +- The value of artifacthub is it's one place for people to index their custom images, and since we depend on each other to learn, it helps grow the community. +- You get to see your pet project listed with the other cool projects in Cloud Native. +- Since the site puts your README front and center, it's a good way to learn how to write a good README, learn some marketing, finding your audience, etc. -Checks the syntax of all `.just` files and the `Justfile`. +[Discussion Thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) -###### `fix` +# Justfile Documentation -Fixes the syntax of all `.just` files and the `Justfile`. +The `Justfile` contains various commands and configurations for building and managing container images and virtual machine images using Podman and other utilities. +To use it, you must have installed [just](https://just.systems/man/en/introduction.html) from your package manager or manually. It is available by default on all Universal Blue images. -###### `clean` +## Environment Variables -Cleans the repository by removing build artifacts. +- `image_name`: The name of the image (default: "image-template"). +- `default_tag`: The default tag for the image (default: "latest"). +- `bib_image`: The Bootc Image Builder (BIB) image (default: "quay.io/centos-bootc/bootc-image-builder:latest"). -##### Build Commands +## Building The Image -###### `build` +### `just build` Builds a container image using Podman. @@ -169,9 +191,11 @@ Arguments: - `$target_image`: The tag you want to apply to the image (default: `$image_name`). - `$tag`: The tag for the image (default: `$default_tag`). -##### Building Virtual Machines and ISOs +## Building and Running Virtual Machines and ISOs + +The below commands all build QCOW2 images. To produce or use a different type of image, substitute in the command with that type in the place of `qcow2`. The available types are `qcow2`, `iso`, and `raw`. -###### `build-qcow2` +### `just build-qcow2` Builds a QCOW2 virtual machine image. @@ -179,49 +203,15 @@ Builds a QCOW2 virtual machine image. just build-qcow2 $target_image $tag ``` -###### `build-raw` - -Builds a RAW virtual machine image. - -```bash -just build-raw $target_image $tag -``` - -###### `build-iso` - -Builds an ISO virtual machine image. - -```bash -just build-iso $target_image $tag -``` - -###### `rebuild-qcow2` +### `just rebuild-qcow2` Rebuilds a QCOW2 virtual machine image. ```bash -just rebuild-qcow2 $target_image $tag -``` - -###### `rebuild-raw` - -Rebuilds a RAW virtual machine image. - -```bash -just rebuild-raw $target_image $tag +just rebuild-vm $target_image $tag ``` -###### `rebuild-iso` - -Rebuilds an ISO virtual machine image. - -```bash -just rebuild-iso $target_image $tag -``` - -##### Run Virtual Machines - -###### `run-vm-qcow2` +### `just run-vm-qcow2` Runs a virtual machine from a QCOW2 image. @@ -229,42 +219,40 @@ Runs a virtual machine from a QCOW2 image. just run-vm-qcow2 $target_image $tag ``` -###### `run-vm-raw` +### `just spawn-vm` -Runs a virtual machine from a RAW image. +Runs a virtual machine using systemd-vmspawn. ```bash -just run-vm-raw $target_image $tag +just spawn-vm rebuild="0" type="qcow2" ram="6G" ``` -###### `run-vm-iso` +## File Management -Runs a virtual machine from an ISO. +### `just check` -```bash -just run-vm-iso $target_image $tag -``` +Checks the syntax of all `.just` files and the `Justfile`. -###### `spawn-vm` +### `just fix` -Runs a virtual machine using systemd-vmspawn. +Fixes the syntax of all `.just` files and the `Justfile`. -```bash -just spawn-vm rebuild="0" type="qcow2" ram="6G" -``` +### `just clean` -##### Lint and Format +Cleans the repository by removing build artifacts. -###### `lint` +### `just lint` Runs shell check on all Bash scripts. -###### `format` +### `just format` Runs shfmt on all Bash scripts. ## Community Examples +These are images derived from this template (or similar enough to this template). Reference them when building your image! + - [m2Giles' OS](https://github.com/m2giles/m2os) - [bOS](https://github.com/bsherman/bos) - [Homer](https://github.com/bketelsen/homer/) |