From 0e4ed297b10402f25cef2bb0e7564751a549585b Mon Sep 17 00:00:00 2001 From: Benjamin Sherman Date: Sat, 26 Aug 2023 10:48:11 -0500 Subject: first commit --- README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..329bb47 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +# ublue-clean-start -- cgit v1.2.3 From 9135f2ddeb003cf96a2b711c89ffae657ac3cf5f Mon Sep 17 00:00:00 2001 From: Benjamin Sherman Date: Sat, 26 Aug 2023 20:09:48 -0500 Subject: refactor: simplify some variable names --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 329bb47..04a0213 100644 --- a/README.md +++ b/README.md @@ -1 +1 @@ -# ublue-clean-start +# ublue-custom-start -- cgit v1.2.3 From 15f8b4fc5f43b5aacac7a62a71b58fe20fc5e83b Mon Sep 17 00:00:00 2001 From: Noel Miller Date: Sun, 3 Mar 2024 19:00:00 -0600 Subject: feat: initial update of readme --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 04a0213..dd8f82f 100644 --- a/README.md +++ b/README.md @@ -1 +1,36 @@ # ublue-custom-start + +# Purpose + +This repository is meant to be used as a template to build your own custom Universal Blue Image. This base template is what the Universal Blue Project uses for all of our new and existing downstream projects (Bazzite, Bluefin, and Ucore). Each project has edited from this template to suit their own individual needs for more advanced build requirements. This template includes a Containerfile and 2 Github workflows (one for building the container and one for building an installation ISO from the container file) that will work immediately out of the box as soon as you enable the workflow in your repository. + +# Prerequisites + +Working knowledge in the following topics: + +- Containers + - Resources: + - https://www.youtube.com/watch?v=SnSH8Ht3MIc + - https://www.mankier.com/5/Containerfile +- rpm-ostree + - Resources: + - https://coreos.github.io/rpm-ostree/ +- Fedora Silverblue (and other Fedora Atomic variants) + - Resources: + - https://docs.fedoraproject.org/en-US/fedora-silverblue/ +- Github Workflows + - Resources: + - https://docs.github.com/en/actions/using-workflows + +# How to Use + +## Template + +Since this is a template repository, you can select `Use this Template` and create a new repository from it. To enable the workflows, you will need to go the actions tab of the new repository and enable the workflows. + +## Containerfile + +This is the main file used to customize the base image you are using. There are several examples of how to add layered rpm-ostree packages + +## Workflows +The `build.yml` workflow creates your OCI container -- cgit v1.2.3 From b9ef601544008145263021653eb63b858cc6626b Mon Sep 17 00:00:00 2001 From: Noel Miller Date: Fri, 12 Apr 2024 11:28:03 -0500 Subject: chore: update readme --- README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index dd8f82f..7beae58 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Purpose -This repository is meant to be used as a template to build your own custom Universal Blue Image. This base template is what the Universal Blue Project uses for all of our new and existing downstream projects (Bazzite, Bluefin, and Ucore). Each project has edited from this template to suit their own individual needs for more advanced build requirements. This template includes a Containerfile and 2 Github workflows (one for building the container and one for building an installation ISO from the container file) that will work immediately out of the box as soon as you enable the workflow in your repository. +This repository is meant to be used as a template to build your own custom Universal Blue Image. This example base template is what the Universal Blue Project uses for all of our new and existing downstream projects (Bazzite, Bluefin, and Ucore). This template includes a Containerfile and 2 Github workflows (one for building the container and one for building an installation ISO from the container file) that will work immediately out of the box as soon as you enable the workflow in your repository. # Prerequisites @@ -33,4 +33,11 @@ Since this is a template repository, you can select `Use this Template` and crea This is the main file used to customize the base image you are using. There are several examples of how to add layered rpm-ostree packages ## Workflows -The `build.yml` workflow creates your OCI container + +### build.yml + +This workflow creates your custom OCI container and publishes it to Github Container Registry. + +### build_iso.yml + +This workflow creates an ISO and uploads it as a Github Artifact. (For examples on how to upload to a cloud registry, feel free to review Bazzite or Bluefin's workflow for uploading to R2.) -- cgit v1.2.3 From bcbb4d46263bf335f27b9a4a5ecc901e97aa6d96 Mon Sep 17 00:00:00 2001 From: Benjamin Sherman Date: Fri, 12 Apr 2024 15:37:55 -0500 Subject: docs: add cosign and cleanup other info --- README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 16 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 7beae58..095ba49 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,82 @@ -# ublue-custom-start +# ublue-custom-template # Purpose -This repository is meant to be used as a template to build your own custom Universal Blue Image. This example base template is what the Universal Blue Project uses for all of our new and existing downstream projects (Bazzite, Bluefin, and Ucore). This template includes a Containerfile and 2 Github workflows (one for building the container and one for building an installation ISO from the container file) that will work immediately out of the box as soon as you enable the workflow in your repository. +This repository is meant to be a template for building your own custom Universal Blue image. This template is the recommended way to make customizations to any image published by the Universal Blue Project: +- [Aurora](https://getaurora.dev/) +- [Bazzite](https://bazzite.gg/) +- [Bluefin](https://projectbluefin.io/) +- [uCore](https://projectucore.io/) +- [main](https://github.com/ublue-os/main/) +- [hwe](https://github.com/ublue-os/hwe/) + +This template includes a Containerfile and a Github workflow for building the container image. As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry. # Prerequisites Working knowledge in the following topics: - Containers - - Resources: - - https://www.youtube.com/watch?v=SnSH8Ht3MIc - - https://www.mankier.com/5/Containerfile + - https://www.youtube.com/watch?v=SnSH8Ht3MIc + - https://www.mankier.com/5/Containerfile - rpm-ostree - - Resources: - - https://coreos.github.io/rpm-ostree/ + - https://coreos.github.io/rpm-ostree/container/ - Fedora Silverblue (and other Fedora Atomic variants) - - Resources: - - https://docs.fedoraproject.org/en-US/fedora-silverblue/ + - https://docs.fedoraproject.org/en-US/fedora-silverblue/ - Github Workflows - - Resources: - - https://docs.github.com/en/actions/using-workflows + - https://docs.github.com/en/actions/using-workflows # How to Use ## Template -Since this is a template repository, you can select `Use this Template` and create a new repository from it. To enable the workflows, you will need to go the actions tab of the new repository and enable the workflows. +Select `Use this Template` and create a new repository from it. To enable the workflows, you will need to go the `Actions` tab of the new repository and click to enable workflows. ## Containerfile -This is the main file used to customize the base image you are using. There are several examples of how to add layered rpm-ostree packages +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 +- modify system files (like /etc/systemd/system.conf) ## Workflows ### build.yml -This workflow creates your custom OCI container and publishes it to Github Container Registry. +This workflow creates your custom OCI image and publishes it to the Github Container Registry (GHCR). + +#### Container Signing + +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. + +This provides users a method of verifying the image. + +1. Install the [cosign CLI tool](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-install-cosign/#installing-cosign-with-the-cosign-binary) + +2. Run inside your repo folder: + + ```bash + cosign generate-key-pair + ``` + + + - 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. + +> [!WARNING] +> Be careful to *never* accidentally commit `cosign.key` into your git repo. + +3. Add the private key to GitHub + + - This can also be done manually. Go to your repository settings, under Secrets and Variables -> Actions + ![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) + 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: + ![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) + + - (CLI instructions) If you have the `github-cli` installed, run: -### build_iso.yml + ```bash + gh secret set SIGNING_SECRET < cosign.key + ``` -This workflow creates an ISO and uploads it as a Github Artifact. (For examples on how to upload to a cloud registry, feel free to review Bazzite or Bluefin's workflow for uploading to R2.) +4. Commit the `cosign.pub` file into your git repository -- cgit v1.2.3 From 276766e8bfb7901a9813ad4dcc1c5ad4b4cbc8a0 Mon Sep 17 00:00:00 2001 From: Benjamin Sherman Date: Fri, 12 Apr 2024 17:00:27 -0500 Subject: docs: change header --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 095ba49..3d34e94 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# ublue-custom-template +# image-template # Purpose -- cgit v1.2.3 From f248afd48be0b48153b3aeb1e79b1001541aa44c Mon Sep 17 00:00:00 2001 From: Benjamin Sherman Date: Fri, 12 Apr 2024 17:03:10 -0500 Subject: docs: update may need to --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3d34e94..df019a3 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Working knowledge in the following topics: ## Template -Select `Use this Template` and create a new repository from it. To enable the workflows, you will need to go the `Actions` tab of the new repository and click to enable workflows. +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. ## Containerfile -- cgit v1.2.3 From 97069176d8f800786f038b9b161677e976925f3b Mon Sep 17 00:00:00 2001 From: Benjamin Sherman Date: Mon, 22 Apr 2024 23:05:49 -0500 Subject: refactor: use repo name as default image name (#7) Also makes the source image's tag easier to understand in the Containerfile. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index df019a3..261102c 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ This file defines the operations used to customize the selected image. It contai ### build.yml -This workflow creates your custom OCI image and publishes it to the Github Container Registry (GHCR). +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. #### Container Signing -- cgit v1.2.3 From 8ca1bedc24caef3fa63aa541b09f698d037be4e0 Mon Sep 17 00:00:00 2001 From: Noel Miller <4983138+noelmiller@users.noreply.github.com> Date: Tue, 30 Apr 2024 15:45:59 -0500 Subject: chore: Update README.md (#19) Remove example that no longer exists. --- README.md | 1 - 1 file changed, 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 261102c..40fe917 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,6 @@ This file defines the operations used to customize the selected image. It contai - change the upstream from which the custom image is derived - add additional RPM packages - add binaries as a layer from other images -- modify system files (like /etc/systemd/system.conf) ## Workflows -- cgit v1.2.3 From c94b77f9bdda407a9795c90fbce175d51d93b291 Mon Sep 17 00:00:00 2001 From: m2 <69128853+m2Giles@users.noreply.github.com> Date: Tue, 19 Nov 2024 17:12:06 -0500 Subject: feat: Add examples of image-template to README (#37) * feat: Add examples of image-template to README * include BK's * Update README.md --- README.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 40fe917..bfb9e86 100644 --- a/README.md +++ b/README.md @@ -79,3 +79,8 @@ This provides users a method of verifying the image. ``` 4. Commit the `cosign.pub` file into your git repository + +### Examples +- [m2os](https://github.com/m2giles/m2os) +- [bos](https://github.com/bsherman/bos) +- [homer](https://github.com/bketelsen/homer/) -- cgit v1.2.3 From e6987e41c04dbb7ead885af609ea7a38affb52da Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 29 Dec 2024 12:52:59 -0500 Subject: Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index bfb9e86..7c86af5 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ This provides users a method of verifying the image. gh secret set SIGNING_SECRET < cosign.key ``` -4. Commit the `cosign.pub` file into your git repository +4. Commit the `cosign.pub` file to the root of your git repository. ### Examples - [m2os](https://github.com/m2giles/m2os) -- cgit v1.2.3 From d158e96fcdfa13610d5ca89a4dc5632533a75203 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sat, 4 Jan 2025 16:55:09 -0500 Subject: docs: update readme (#46) --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 7c86af5..e0a2303 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,9 @@ Working knowledge in the following topics: - Containers - https://www.youtube.com/watch?v=SnSH8Ht3MIc - https://www.mankier.com/5/Containerfile -- rpm-ostree - - https://coreos.github.io/rpm-ostree/container/ +- bootc + - https://containers.github.io/bootc/ + - https://github.com/containers/bootc/discussions - Forum for bootc, this is probably the best place to ask questions! - Fedora Silverblue (and other Fedora Atomic variants) - https://docs.fedoraproject.org/en-US/fedora-silverblue/ - Github Workflows -- cgit v1.2.3 From 87f44a23654da0e858c02cb315122e3a16a563c1 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sat, 4 Jan 2025 17:12:41 -0500 Subject: Update README.md --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index e0a2303..e5ee449 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,10 @@ This repository is meant to be a template for building your own custom Universal This template includes a Containerfile and a Github workflow for building the container image. As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry. +# Community + +- [**bootc discussion forums**](https://github.com/containers/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. + # Prerequisites Working knowledge in the following topics: @@ -21,7 +25,6 @@ Working knowledge in the following topics: - https://www.mankier.com/5/Containerfile - bootc - https://containers.github.io/bootc/ - - https://github.com/containers/bootc/discussions - Forum for bootc, this is probably the best place to ask questions! - Fedora Silverblue (and other Fedora Atomic variants) - https://docs.fedoraproject.org/en-US/fedora-silverblue/ - Github Workflows -- cgit v1.2.3 From d251964f09d872d46313aefcdde1c2e4db0fe4fe Mon Sep 17 00:00:00 2001 From: Tulip Blossom Date: Sun, 5 Jan 2025 12:33:03 -0300 Subject: feat: add artifacthub metadata by default and WIP README (#48) --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index e5ee449..41082bc 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,12 @@ This template includes a Containerfile and a Github workflow for building the co - [**bootc discussion forums**](https://github.com/containers/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. +## ArtifactHub + +ArtifactHub is - PLACEHOLDER + +- [**artifacthub universal blue index**](https://artifacthub.io/packages/search?ts_query_web=ublue&sort=relevance&page=1) + # Prerequisites Working knowledge in the following topics: -- cgit v1.2.3 From 576a6550810d86b2a1af7dee93dc045e83b1934f Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 5 Jan 2025 10:36:12 -0500 Subject: docs: add artifacthub to readme (#49) --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 41082bc..4dc787e 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,7 @@ This template includes a Containerfile and a Github workflow for building the co # Community - [**bootc discussion forums**](https://github.com/containers/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. - -## ArtifactHub - -ArtifactHub is - PLACEHOLDER - -- [**artifacthub universal blue index**](https://artifacthub.io/packages/search?ts_query_web=ublue&sort=relevance&page=1) +- Index your image on [artifacthub.io](https://artifacthub.io), use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. # Prerequisites -- cgit v1.2.3 From aa88c6e60398d1484ea391bb0e0cbdfd01e96c99 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 5 Jan 2025 10:37:26 -0500 Subject: Update README.md (#50) --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 4dc787e..507b376 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,6 @@ This repository is meant to be a template for building your own custom Universal This template includes a Containerfile and a Github workflow for building the container image. As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry. -# Community - -- [**bootc discussion forums**](https://github.com/containers/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. -- Index your image on [artifacthub.io](https://artifacthub.io), use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. - # Prerequisites Working knowledge in the following topics: @@ -85,7 +80,13 @@ This provides users a method of verifying the image. 4. Commit the `cosign.pub` file to the root of your git repository. -### Examples +# Community + +- [**bootc discussion forums**](https://github.com/containers/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. +- Index your image on [artifacthub.io](https://artifacthub.io), use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. + +## Community Examples + - [m2os](https://github.com/m2giles/m2os) - [bos](https://github.com/bsherman/bos) - [homer](https://github.com/bketelsen/homer/) -- cgit v1.2.3 From 707c85ca9b6aa78290130f8cf57321b433701505 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Wed, 8 Jan 2025 19:28:28 -0500 Subject: Update README.md --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 507b376..bb784aa 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,12 @@ This file defines the operations used to customize the selected image. It contai - add additional RPM packages - add binaries as a layer from other images +## Building an ISO + +Modify `iso.toml` to point to your custom image before generating an ISO. + +- (Steps in progress) + ## Workflows ### build.yml -- cgit v1.2.3 From 47fc39df95b4fad0bbe967d5a13e8ece48f300ce Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Fri, 24 Jan 2025 09:04:53 -0500 Subject: docs: update README.md --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index bb784aa..bc16c9d 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,15 @@ This repository is meant to be a template for building your own custom Universal - [Bluefin](https://projectbluefin.io/) - [uCore](https://projectucore.io/) - [main](https://github.com/ublue-os/main/) -- [hwe](https://github.com/ublue-os/hwe/) +- [hwe](https://github.com/ublue-os/hwe/) -This template includes a Containerfile and a Github workflow for building the container image. As soon as the workflow is enabled in your repository, it will build the container image and push it to the Github Container Registry. +or any other base image: + +- CentOS Stream 9: `quay.io/centos-bootc/centos-bootc:stream9` +- CentOS Stream 10 (in development): `quay.io/centos-bootc/centos-bootc:stream10` +- Fedora: `quay.io/fedora/fedora-bootc:41` + +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. # Prerequisites -- cgit v1.2.3 From 3152d364b8f2fa28502e78efd4b835654c04b290 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Fri, 24 Jan 2025 09:05:36 -0500 Subject: Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index bc16c9d..492ee7b 100644 --- a/README.md +++ b/README.md @@ -10,11 +10,11 @@ This repository is meant to be a template for building your own custom Universal - [main](https://github.com/ublue-os/main/) - [hwe](https://github.com/ublue-os/hwe/) -or any other base image: +or any other base image if you want to start from scratch: +- Fedora: `quay.io/fedora/fedora-bootc:41` - CentOS Stream 9: `quay.io/centos-bootc/centos-bootc:stream9` - CentOS Stream 10 (in development): `quay.io/centos-bootc/centos-bootc:stream10` -- Fedora: `quay.io/fedora/fedora-bootc:41` 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. -- cgit v1.2.3 From 2a5452862bd6d2db1947420e654878c025401478 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Fri, 24 Jan 2025 09:33:11 -0500 Subject: docs: add discussion links --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 492ee7b..0cd1a5d 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ This provides users a method of verifying the image. # Community - [**bootc discussion forums**](https://github.com/containers/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. -- Index your image on [artifacthub.io](https://artifacthub.io), use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. +- Index your image on [artifacthub.io](https://artifacthub.io), use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. [Discussion thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) ## Community Examples -- cgit v1.2.3 From 4e461eccd9813a485093db1ff85a27cfd0410672 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Wed, 12 Mar 2025 01:32:44 -0400 Subject: Update README.md --- README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0cd1a5d..f5c2fb1 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,16 @@ This provides users a method of verifying the image. # Community - [**bootc discussion forums**](https://github.com/containers/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. -- Index your image on [artifacthub.io](https://artifacthub.io), use the `artifacthub-repo.yml` file at the root to verify yourself as the publisher. [Discussion thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) + +## Artifacthub + +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 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. + +[Discussion thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) ## Community Examples -- cgit v1.2.3 From d100709c604b74f153714bd888a6088a2d5555f5 Mon Sep 17 00:00:00 2001 From: Robert Sturla Date: Thu, 13 Mar 2025 00:20:26 +0000 Subject: fix(docs): update link to bootc docs (#77) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f5c2fb1..c27dbaa 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Working knowledge in the following topics: - https://www.youtube.com/watch?v=SnSH8Ht3MIc - https://www.mankier.com/5/Containerfile - bootc - - https://containers.github.io/bootc/ + - https://bootc-dev.github.io/bootc/ - Fedora Silverblue (and other Fedora Atomic variants) - https://docs.fedoraproject.org/en-US/fedora-silverblue/ - Github Workflows @@ -94,7 +94,7 @@ This provides users a method of verifying the image. # Community -- [**bootc discussion forums**](https://github.com/containers/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. +- [**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. ## Artifacthub -- cgit v1.2.3 From 28681f9687186850284226a01f4f4396d25c3b58 Mon Sep 17 00:00:00 2001 From: Sean Date: Thu, 13 Mar 2025 19:30:38 -0500 Subject: feat(build-iso): Add ability to generate ISO (#79) * initial commit of s3 upload for iso * Updated Readme. Updated build-iso.yml from testing in test repo * one more note to make it look more balanced * add artifact upload ability and adjust README to detail how to use * One more final note to help be explicit about artifact location. --------- Co-authored-by: Sean Thrailkill --- README.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c27dbaa..e79c500 100644 --- a/README.md +++ b/README.md @@ -47,9 +47,9 @@ This file defines the operations used to customize the selected image. It contai ## Building an ISO -Modify `iso.toml` to point to your custom image before generating an ISO. +This template provides an out of the box workflow for getting an ISO image for your custom OCI image which can be used to directly install onto your machines. -- (Steps in progress) +This template provides a way to upload the ISO 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). ## Workflows @@ -57,6 +57,22 @@ Modify `iso.toml` to point to your custom image before generating an ISO. 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. +### build-iso.yml + +This workflow creates an ISO from your OCI image by utilizing the [bootc-image-builder](https://osbuild.org/docs/bootc/) to generate an ISO. In order to use this workflow you must complete the following steps: + +- Modify `iso.toml` to point to your custom image before generating an ISO. +- If you changed your image name from the default in `build.yml` then in the `build-iso.yml` file edit the `IMAGE_REGISTRY` 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 ISOs 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. + +Once the workflow is done, you'll find it either in your S3 bucket or as part of the summary under `Artifacts` after the workflow is completed. + #### Container Signing 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. @@ -79,7 +95,7 @@ This provides users a method of verifying the image. 3. Add the private key to GitHub - - This can also be done manually. Go to your repository settings, under Secrets and Variables -> Actions + - This can also be done manually. Go to your repository settings, under `Secrets and Variables` -> `Actions` ![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) 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: ![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) -- cgit v1.2.3 From f688713285a45cb7999824a64aedb1714712488d Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Tue, 25 Mar 2025 17:27:52 -0400 Subject: docs: document the justfile (#91) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: document the justfile Bless you copilot. 🗡️ * Update README.md Co-authored-by: Tulip Blossom --------- Co-authored-by: Tulip Blossom --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index e79c500..0f50ffa 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,151 @@ This template provides an out of the box workflow for getting an ISO image for y This template provides a way to upload the ISO 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). +### Justfile Documentation + +This `Justfile` contains various commands and configurations for building and managing container images and virtual machine images using Podman and other utilities. + +#### Environment Variables + +- `repo_organization`: The GitHub repository owner (default: "yourname"). +- `image_name`: The name of the image (default: "yourimage"). +- `centos_version`: The CentOS version (default: "stream10"). +- `fedora_version`: The Fedora version (default: "41"). +- `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"). + +#### Aliases + +- `build-vm`: Alias for `build-qcow2`. +- `rebuild-vm`: Alias for `rebuild-qcow2`. +- `run-vm`: Alias for `run-vm-qcow2`. + + +#### Commands + +###### `check` + +Checks the syntax of all `.just` files and the `Justfile`. + +###### `fix` + +Fixes the syntax of all `.just` files and the `Justfile`. + +###### `clean` + +Cleans the repository by removing build artifacts. + +##### Build Commands + +###### `build` + +Builds a container image using Podman. + +```bash +just build $target_image $tag $dx $hwe $gdx +``` + +Arguments: +- `$target_image`: The tag you want to apply to the image (default: aurora). +- `$tag`: The tag for the image (default: lts). +- `$dx`: Enable DX (default: "0"). +- `$hwe`: Enable HWE (default: "0"). +- `$gdx`: Enable GDX (default: "0"). + +##### Building Virtual Machines and ISOs + +###### `build-qcow2` + +Builds a QCOW2 virtual machine image. + +```bash +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` + +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 +``` + +###### `rebuild-iso` + +Rebuilds an ISO virtual machine image. + +```bash +just rebuild-iso $target_image $tag +``` + +##### Run Virtual Machines + +###### `run-vm-qcow2` + +Runs a virtual machine from a QCOW2 image. + +```bash +just run-vm-qcow2 $target_image $tag +``` + +###### `run-vm-raw` + +Runs a virtual machine from a RAW image. + +```bash +just run-vm-raw $target_image $tag +``` + +###### `run-vm-iso` + +Runs a virtual machine from an ISO. + +```bash +just run-vm-iso $target_image $tag +``` + +###### `spawn-vm` + +Runs a virtual machine using systemd-vmspawn. + +```bash +just spawn-vm rebuild="0" type="qcow2" ram="6G" +``` + +##### Lint and Format + +###### `lint` + +Runs shell check on all Bash scripts. + +###### `format` + +Runs shfmt on all Bash scripts. + ## Workflows ### build.yml -- cgit v1.2.3 From 1a4f12ad1a51d9084e307e14e65350655f2c4fc2 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 27 Apr 2025 21:27:01 -0400 Subject: Update README.md --- README.md | 143 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 72 insertions(+), 71 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0f50ffa..629e3b0 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,78 @@ This template provides an out of the box workflow for getting an ISO image for y This template provides a way to upload the ISO 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). +## Workflows + +### build.yml + +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. + +### build-iso.yml + +This workflow creates an ISO from your OCI image by utilizing the [bootc-image-builder](https://osbuild.org/docs/bootc/) to generate an ISO. In order to use this workflow you must complete the following steps: + +- Modify `iso.toml` to point to your custom image before generating an ISO. +- If you changed your image name from the default in `build.yml` then in the `build-iso.yml` file edit the `IMAGE_REGISTRY` 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 ISOs 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. + +Once the workflow is done, you'll find it either in your S3 bucket or as part of the summary under `Artifacts` after the workflow is completed. + +#### Container Signing + +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. + +This provides users a method of verifying the image. + +1. Install the [cosign CLI tool](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-install-cosign/#installing-cosign-with-the-cosign-binary) + +2. Run inside your repo folder: + + ```bash + cosign generate-key-pair + ``` + + + - 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. + +> [!WARNING] +> Be careful to *never* accidentally commit `cosign.key` into your git repo. + +3. Add the private key to GitHub + + - This can also be done manually. Go to your repository settings, under `Secrets and Variables` -> `Actions` + ![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) + 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: + ![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) + + - (CLI instructions) If you have the `github-cli` installed, run: + + ```bash + gh secret set SIGNING_SECRET < cosign.key + ``` + +4. Commit the `cosign.pub` file to the root of your git repository. + +# Community + +- [**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. + +## Artifacthub + +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 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. + +[Discussion thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) + + ### Justfile Documentation This `Justfile` contains various commands and configurations for building and managing container images and virtual machine images using Podman and other utilities. @@ -196,77 +268,6 @@ Runs shell check on all Bash scripts. Runs shfmt on all Bash scripts. -## Workflows - -### build.yml - -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. - -### build-iso.yml - -This workflow creates an ISO from your OCI image by utilizing the [bootc-image-builder](https://osbuild.org/docs/bootc/) to generate an ISO. In order to use this workflow you must complete the following steps: - -- Modify `iso.toml` to point to your custom image before generating an ISO. -- If you changed your image name from the default in `build.yml` then in the `build-iso.yml` file edit the `IMAGE_REGISTRY` 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 ISOs 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. - -Once the workflow is done, you'll find it either in your S3 bucket or as part of the summary under `Artifacts` after the workflow is completed. - -#### Container Signing - -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. - -This provides users a method of verifying the image. - -1. Install the [cosign CLI tool](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-install-cosign/#installing-cosign-with-the-cosign-binary) - -2. Run inside your repo folder: - - ```bash - cosign generate-key-pair - ``` - - - - 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. - -> [!WARNING] -> Be careful to *never* accidentally commit `cosign.key` into your git repo. - -3. Add the private key to GitHub - - - This can also be done manually. Go to your repository settings, under `Secrets and Variables` -> `Actions` - ![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) - 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: - ![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) - - - (CLI instructions) If you have the `github-cli` installed, run: - - ```bash - gh secret set SIGNING_SECRET < cosign.key - ``` - -4. Commit the `cosign.pub` file to the root of your git repository. - -# Community - -- [**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. - -## Artifacthub - -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 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. - -[Discussion thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) - ## Community Examples - [m2os](https://github.com/m2giles/m2os) -- cgit v1.2.3 From 8fd7a32fc3cdd8d7165e3d53fa9daad2e831e15c Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 27 Apr 2025 21:30:26 -0400 Subject: Update README.md --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 629e3b0..8828991 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,12 @@ Working knowledge in the following topics: - Github Workflows - https://docs.github.com/en/actions/using-workflows +# Video Tutorial + +TesterTech has made a tutorial video, check it out: + +[![Video Tutorial](https://img.youtube.com/vi/IxBl11Zmq5w/0.jpg)](https://www.youtube.com/watch?v=IxBl11Zmq5wE) + # How to Use ## Template -- cgit v1.2.3 From 3faa539e8b68b477392e1359d34d831276b05a0b Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Mon, 28 Apr 2025 03:32:25 +0200 Subject: Update README.md (#101) --- README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8828991..b853805 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,8 @@ # Purpose This repository is meant to be a template for building your own custom Universal Blue image. This template is the recommended way to make customizations to any image published by the Universal Blue Project: -- [Aurora](https://getaurora.dev/) -- [Bazzite](https://bazzite.gg/) -- [Bluefin](https://projectbluefin.io/) -- [uCore](https://projectucore.io/) -- [main](https://github.com/ublue-os/main/) -- [hwe](https://github.com/ublue-os/hwe/) +- 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. or any other base image if you want to start from scratch: -- cgit v1.2.3 From 6bc04472cd8d69ba90c2e380afc3d20579ad97b7 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 27 Apr 2025 21:35:49 -0400 Subject: Update README.md --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index b853805..97f09ac 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,7 @@ This repository is meant to be a template for building your own custom Universal or any other base image if you want to start from scratch: - Fedora: `quay.io/fedora/fedora-bootc:41` -- CentOS Stream 9: `quay.io/centos-bootc/centos-bootc:stream9` -- CentOS Stream 10 (in development): `quay.io/centos-bootc/centos-bootc:stream10` +- CentOS Stream 10: `quay.io/centos-bootc/centos-bootc:stream10` 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. -- cgit v1.2.3 From 5e12ce70c02c65e3c9c581ab8efc570c32ab320b Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 27 Apr 2025 22:28:17 -0400 Subject: Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 97f09ac..9ada6bb 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Purpose -This repository is meant to be a template for building your own custom Universal Blue 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. -- cgit v1.2.3 From 2dcbaa2b4ab383ac3a45e5efe080849e5ffd8b5e Mon Sep 17 00:00:00 2001 From: Freya Gustavsson Date: Mon, 5 May 2025 18:21:58 +0200 Subject: feat: Add more community examples (#103) This adds two more example bootc images that are based off of this template. One of which is my own VeneOS and the other being Amy OS. Signed-off-by: Freya Gustavsson --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 9ada6bb..609f6c8 100644 --- a/README.md +++ b/README.md @@ -271,6 +271,8 @@ Runs shfmt on all Bash scripts. ## Community Examples -- [m2os](https://github.com/m2giles/m2os) -- [bos](https://github.com/bsherman/bos) -- [homer](https://github.com/bketelsen/homer/) +- [m2Giles' OS](https://github.com/m2giles/m2os) +- [bOS](https://github.com/bsherman/bos) +- [Homer](https://github.com/bketelsen/homer/) +- [Amy OS](https://github.com/astrovm/amyos) +- [VeneOS](https://github.com/Venefilyn/veneos) -- cgit v1.2.3 From 3e88d8228dc12c32c316d8be1b638e17ccbdeeed Mon Sep 17 00:00:00 2001 From: Christian Glombek Date: Tue, 10 Jun 2025 02:15:44 +0200 Subject: chore: simplify (#111) --- README.md | 32 +++++++++++++------------------- 1 file changed, 13 insertions(+), 19 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 609f6c8..86aaf76 100644 --- a/README.md +++ b/README.md @@ -46,11 +46,11 @@ This file defines the operations used to customize the selected image. It contai - add additional RPM packages - add binaries as a layer from other images -## Building an ISO +## Building disk images -This template provides an out of the box workflow for getting an ISO image for your custom OCI image which can be used to directly install onto your machines. +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. -This template provides a way to upload the ISO 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). +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). ## Workflows @@ -58,13 +58,13 @@ This template provides a way to upload the ISO that is generated from the workfl 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. -### build-iso.yml +### build-disk.yml -This workflow creates an ISO from your OCI image by utilizing the [bootc-image-builder](https://osbuild.org/docs/bootc/) to generate an ISO. In order to use this workflow you must complete the following steps: +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: -- Modify `iso.toml` to point to your custom image before generating an ISO. -- If you changed your image name from the default in `build.yml` then in the `build-iso.yml` file edit the `IMAGE_REGISTRY` 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 ISOs 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 +- 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 @@ -72,7 +72,7 @@ This workflow creates an ISO from your OCI image by utilizing the [bootc-image-b - `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. -Once the workflow is done, you'll find it either in your S3 bucket or as part of the summary under `Artifacts` after the workflow is completed. +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. #### Container Signing @@ -130,10 +130,7 @@ This `Justfile` contains various commands and configurations for building and ma #### Environment Variables -- `repo_organization`: The GitHub repository owner (default: "yourname"). -- `image_name`: The name of the image (default: "yourimage"). -- `centos_version`: The CentOS version (default: "stream10"). -- `fedora_version`: The Fedora version (default: "41"). +- `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"). @@ -165,15 +162,12 @@ Cleans the repository by removing build artifacts. Builds a container image using Podman. ```bash -just build $target_image $tag $dx $hwe $gdx +just build $target_image $tag ``` Arguments: -- `$target_image`: The tag you want to apply to the image (default: aurora). -- `$tag`: The tag for the image (default: lts). -- `$dx`: Enable DX (default: "0"). -- `$hwe`: Enable HWE (default: "0"). -- `$gdx`: Enable GDX (default: "0"). +- `$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 -- cgit v1.2.3 From 4cbaf5f55a0eec7c237ce6377ed1c143f9cceb7f Mon Sep 17 00:00:00 2001 From: Brennen Puth Date: Sat, 2 Aug 2025 09:18:43 -0400 Subject: docs(README): Giving the README a fresh coat of paint (#123) * Full README spruce-up * First glance changes * Bring community section into line * Quick wording fix * Add Fedora Atomic to list of bootc systems * Add to base image instructions and take some content out of first paragraph * Better repository contents section * Remove TODO and reword community section again --- README.md | 292 ++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 140 insertions(+), 152 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 86aaf76..490c5e6 100644 --- a/README.md +++ b/README.md @@ -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 +[![Video Tutorial](https://img.youtube.com/vi/IxBl11Zmq5w/0.jpg)](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 -[![Video Tutorial](https://img.youtube.com/vi/IxBl11Zmq5w/0.jpg)](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: +
+ Using the Github Web Interface (preferred) -- 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` + ![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) + 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: + ![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) +
+
+Using the Github CLI -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 +``` +
-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) +
+ Base Images -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). +
- - - 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` - ![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) - 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: - ![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) +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// +``` +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/) -- cgit v1.2.3 From 974c121d223120ae707d1236bf1ebd1d27ae8205 Mon Sep 17 00:00:00 2001 From: Jordan Petridis <16531710+alatiera@users.noreply.github.com> Date: Fri, 22 Aug 2025 20:47:22 +0300 Subject: docs: Skip password promot during cosign key generation (#131) The key in GH secret requires that its not password protected in order to work. Add COSIGN_PASSWORD="" in the example command so everyone that copy pastes it avoids the prompt they have to manually ignore otherwise. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 490c5e6..e890f6a 100644 --- a/README.md +++ b/README.md @@ -49,10 +49,10 @@ First, install the [cosign CLI tool](https://edu.chainguard.dev/open-source/sigs With the cosign tool installed, run inside your repo folder: ```bash -cosign generate-key-pair +COSIGN_PASSWORD="" cosign generate-key-pair ``` -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. +The signing key will be used in GitHub Actions and will not work if it is password protected. > [!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. -- cgit v1.2.3 From c26a1667864ca1c93ff2cec255ea1c3b9c3f03a2 Mon Sep 17 00:00:00 2001 From: Matthias an der Ruhr <135343836+Matthias-adR@users.noreply.github.com> Date: Sun, 19 Oct 2025 17:56:08 +0200 Subject: Update README.md (#145) Fix formatting of text under dropdowns (image previews; hyperlinks) --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index e890f6a..b062592 100644 --- a/README.md +++ b/README.md @@ -62,10 +62,10 @@ Next, you need to add the key to GitHub. This makes use of GitHub's secret signi
Using the Github Web Interface (preferred) - Go to your repository settings, under `Secrets and Variables` -> `Actions` - ![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) - 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: - ![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) +Go to your repository settings, under `Secrets and Variables` -> `Actions` +![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) +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: +![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png)
Using the Github CLI @@ -85,13 +85,13 @@ For a base image, you can choose any of the Universal Blue images or start from
Base Images - - 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` +- 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` - You can find more Universal Blue images on the [packages page](https://github.com/orgs/ublue-os/packages). +You can find more Universal Blue images on the [packages page](https://github.com/orgs/ublue-os/packages).
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: -- cgit v1.2.3 From 9ff45df6eaa8650844ad0627827bfdaa076048a5 Mon Sep 17 00:00:00 2001 From: DXC-0 Date: Tue, 4 Nov 2025 08:40:01 +0000 Subject: docs: add akmods section (#160) --- README.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index b062592..ba52ebf 100644 --- a/README.md +++ b/README.md @@ -249,6 +249,10 @@ Runs shell check on all Bash scripts. Runs shfmt on all Bash scripts. +## Additional resources + +For additional driver support, ublue maintains a set of scripts and container images available at [ublue-akmod](https://github.com/ublue-os/akmods). These images include the necessary scripts to install multiple kernel drivers within the container (Nvidia, OpenRazer, Framework...). The documentation provides guidance on how to properly integrate these drivers into your container image. + ## Community Examples These are images derived from this template (or similar enough to this template). Reference them when building your image! -- cgit v1.2.3 From a65bb3da1f7c5ed04ac3d8b5f69878c5ecee14ea Mon Sep 17 00:00:00 2001 From: renner <80410025+renner0e@users.noreply.github.com> Date: Wed, 17 Jun 2026 16:16:34 +0200 Subject: refactor: rewrite in just, saner defaults (#218) * refactor: rewrite in just, saner defaults I think it makes sense to do this as it is longterm easier to maintain, locally iterate and extend. Documents how to rebase to a local image, it pains me greatly when people iterate on github and wait forever for things to build and then to download the image for trivial things they could also quickly do locally. Rpm-ostree rechunker by default instead of opt-in legacy-rechunker, chunkah is also available if people want to use it already, if we deem it ready then we can enable it later on. They can all be opted-out of. Have a way to copy files to /{usr,etc} by default. We should sign the digest of the image instead of the tag. Co-Authored-by: a lot of sugar and bad music * docs: bump fedora-bootc version Co-authored-by: Jill Fiore * fix: formatting inconsistency Co-authored-by: Jill Fiore * docs: remove variable mentions from workflows These are now defined in the image-template.env file * fix: small nits in labels Co-authored-by: Adam Fidel --------- Co-authored-by: Jill Fiore Co-authored-by: Adam Fidel --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 46 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index ba52ebf..64250be 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ For a base image, you can choose any of the Universal Blue images or start from - 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` +- Fedora: `quay.io/fedora/fedora-bootc:44` You can find more Universal Blue images on the [packages page](https://github.com/orgs/ublue-os/packages).
@@ -102,11 +102,11 @@ This will show you all the info you need to know about your current image. The i ### Step 2c: Changing Names -Change the first line in the [Justfile](./Justfile) to your image's name. +Change the `IMAGE_NAME` and `REPO_ORGANIZATION` variable inside the `image-template.env` 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 add Containerfile image-template.env cosign.pub git commit -m "Initial Setup" git push ``` @@ -132,7 +132,7 @@ The [build.sh](./build_files/build.sh) file is called from your Containerfile. I ## build.yml -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. +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. # Building Disk Images @@ -173,12 +173,16 @@ To use it, you must have installed [just](https://just.systems/man/en/introducti ## Environment Variables +These are all sourced from the `image-template.env` file. + - `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"). ## Building The Image +All these recipes will work (with default values) without supplying any arguments to them, e.g. `just build` + ### `just build` Builds a container image using Podman. @@ -191,6 +195,44 @@ Arguments: - `$target_image`: The tag you want to apply to the image (default: `$image_name`). - `$tag`: The tag for the image (default: `$default_tag`). +### Rechunking +We can flatten the layers of container images to make sure there isn't a single huge layer when your image gets published. +This does not make your image faster to download, just provides better resumability. + +#### `just ostree-rechunk` +Rechunks the existing Image with [rpm-ostree](https://coreos.github.io/rpm-ostree/build-chunked-oci/) + +```bash +just ostree-rechunk $target_image $tag +``` + +#### `just rechunk` +Rechunks the existing Image with [chunkah](https://github.com/coreos/chunkah), this is probably gonna be the default here at some point, try it out, it's cool. + +```bash +just rechunk $target_image $tag +``` + +### Switching to the locally built image for testing + +The image has to be in the containers-storage owned by root, to be able to rebase to it, see the `_rootful_load_image` recipe. + +`sudo just build` and `sudo just ostree-rechunk` builds directly as root and allows you to skip the transfer to the root containers-storage. + +You can rebase to all the images that are in your containers-storage: + +``` +sudo podman image list --filter=label=containers.bootc=1 +``` + +See [man bootc switch](https://bootc.dev/bootc/man/bootc-switch.8.html) for more info. + +``` +sudo bootc switch --transport containers-storage localhost/myimage:latest +``` + +and reboot your system! + ## 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`. -- cgit v1.2.3 From ed40e44b610cac878f17fa4233d8e3d19b8d67bb Mon Sep 17 00:00:00 2001 From: tranch Date: Thu, 9 Jul 2026 16:53:52 +0800 Subject: Configure AeroCore image mirrors Add build-time mirror configuration for Flatpak and Homebrew, expose the related build args, and install an AeroCore-owned profile script to load mirror environment files. Rename the mirror configuration files from the Bazzite-prefixed names to AeroCore-prefixed names while keeping the upstream Bazzite helper reference intact. Verification: bash -n system_files/etc/profile.d/aerocore-mirrors.sh && bash -n build_files/build.sh --- README.md | 303 ++++---------------------------------------------------------- 1 file changed, 17 insertions(+), 286 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 64250be..fdd7c76 100644 --- a/README.md +++ b/README.md @@ -1,306 +1,37 @@ -# image-template +# AeroCore OS -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. +A customized Bazzite-deck image tailored for living-room HTPCs, featuring China-localized updates and an integrated game accelerator. -# Community +AeroCore OS is built on top of the `ublue-os/image-template` ecosystem. Unlike a heavy fork of `ublue-os/bazzite`, AeroCore OS adopts a **layered architecture** that starts directly from a pre-built upstream Bazzite image: -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. +```dockerfile +FROM ghcr.io/ublue-os/bazzite-deck:stable -# How to Use - -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. - -[![Video Tutorial](https://img.youtube.com/vi/IxBl11Zmq5w/0.jpg)](https://www.youtube.com/watch?v=IxBl11Zmq5wE) - -## Step 0: Prerequisites - -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 - -## Step 1: Preparing the Template - -### Step 1a: Copying the Template - -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. - -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. - -### Step 1b: Cloning the New Repository - -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) - -Once you have the repository on your local drive, proceed to the next step. - -## Step 2: Initial Setup - -### Step 2a: Creating a Cosign Key - -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. - -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: - -```bash -COSIGN_PASSWORD="" cosign generate-key-pair -``` - -The signing key will be used in GitHub Actions and will not work if it is password protected. - -> [!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. - -Next, you need to add the key to GitHub. This makes use of GitHub's secret signing system. - -
- Using the Github Web Interface (preferred) - -Go to your repository settings, under `Secrets and Variables` -> `Actions` -![image](https://user-images.githubusercontent.com/1264109/216735595-0ecf1b66-b9ee-439e-87d7-c8cc43c2110a.png) -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: -![image](https://user-images.githubusercontent.com/1264109/216735690-2d19271f-cee2-45ac-a039-23e6a4c16b34.png) -
-
-Using the Github CLI - -If you have the `github-cli` installed, run: - -```bash -gh secret set SIGNING_SECRET < cosign.key -``` -
- -### Step 2b: Choosing Your Base 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. - -
- Base Images - -- 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:44` - -You can find more Universal Blue images on the [packages page](https://github.com/orgs/ublue-os/packages). -
- -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. - -### Step 2c: Changing Names - -Change the `IMAGE_NAME` and `REPO_ORGANIZATION` variable inside the `image-template.env` - -To commit and push all the files changed and added in step 2 into your Github repository: -```bash -git add Containerfile image-template.env 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! - -## Step 3: Switch to Your Image - -From your bootc system, run the following command substituting in your Github username and image name where noted. -```bash -sudo bootc switch ghcr.io// -``` -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. - -# Repository Contents - -## Containerfile - -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). - -## build.sh - -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. - -## build.yml - -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. - -# Building Disk Images - -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 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/). - -## Setting Up ISO Builds - -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: - -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. - -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 - -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 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. - -[Discussion Thread](https://universal-blue.discourse.group/t/listing-your-custom-image-on-artifacthub/6446) - -# Justfile Documentation - -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. - -## Environment Variables - -These are all sourced from the `image-template.env` file. - -- `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"). - -## Building The Image - -All these recipes will work (with default values) without supplying any arguments to them, e.g. `just build` - -### `just build` - -Builds a container image using Podman. - -```bash -just build $target_image $tag -``` - -Arguments: -- `$target_image`: The tag you want to apply to the image (default: `$image_name`). -- `$tag`: The tag for the image (default: `$default_tag`). - -### Rechunking -We can flatten the layers of container images to make sure there isn't a single huge layer when your image gets published. -This does not make your image faster to download, just provides better resumability. - -#### `just ostree-rechunk` -Rechunks the existing Image with [rpm-ostree](https://coreos.github.io/rpm-ostree/build-chunked-oci/) - -```bash -just ostree-rechunk $target_image $tag ``` -#### `just rechunk` -Rechunks the existing Image with [chunkah](https://github.com/coreos/chunkah), this is probably gonna be the default here at some point, try it out, it's cool. - -```bash -just rechunk $target_image $tag -``` +By focusing strictly on file overlays and configuration writing, this build intentionally avoids invasive operations like `dnf5 install/remove`, COPR enablement, akmods pulls, or kernel recompilations. This architectural choice keeps AeroCore OS completely immune to Fedora/COPR dependency drift during major upstream transition windows (e.g., Bazzite 43 to 44). -### Switching to the locally built image for testing +--- -The image has to be in the containers-storage owned by root, to be able to rebase to it, see the `_rootful_load_image` recipe. +## Key Features & Optimizations -`sudo just build` and `sudo just ostree-rechunk` builds directly as root and allows you to skip the transfer to the root containers-storage. +* **Couch-Gaming Tailored:** Optimized settings for a seamless, out-of-the-box living-room console experience. +* **China-Localized Mirrors:** Pre-configured environment setups (e.g., `/etc/environment.d/99-aerocore-mirrors.conf`) utilizing low-latency, mainland China-hosted update streams. +* **Integrated Game Accelerator:** Embedded network booster configuration to ensure low-latency connection for Steam and local gaming services. +* **Maintainable Overlay Structure:** Structured `system_files/` directory for robust, long-term AeroCore core file injection without touching upstream packages. -You can rebase to all the images that are in your containers-storage: - -``` -sudo podman image list --filter=label=containers.bootc=1 -``` - -See [man bootc switch](https://bootc.dev/bootc/man/bootc-switch.8.html) for more info. - -``` -sudo bootc switch --transport containers-storage localhost/myimage:latest -``` +## Local Build -and reboot your system! - -## 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`. - -### `just build-qcow2` - -Builds a QCOW2 virtual machine image. +To build AeroCore OS locally, edit `image-template.env` to match your target configurations and then run: ```bash -just build-qcow2 $target_image $tag -``` - -### `just rebuild-qcow2` +just build -Rebuilds a QCOW2 virtual machine image. - -```bash -just rebuild-vm $target_image $tag ``` -### `just run-vm-qcow2` - -Runs a virtual machine from a QCOW2 image. +To test a different upstream base image directly without modifying the environment files: ```bash -just run-vm-qcow2 $target_image $tag -``` - -### `just spawn-vm` - -Runs a virtual machine using systemd-vmspawn. +BASE_IMAGE=ghcr.io/ublue-os/bazzite-deck:testing just build -```bash -just spawn-vm rebuild="0" type="qcow2" ram="6G" ``` - -## File Management - -### `just check` - -Checks the syntax of all `.just` files and the `Justfile`. - -### `just fix` - -Fixes the syntax of all `.just` files and the `Justfile`. - -### `just clean` - -Cleans the repository by removing build artifacts. - -### `just lint` - -Runs shell check on all Bash scripts. - -### `just format` - -Runs shfmt on all Bash scripts. - -## Additional resources - -For additional driver support, ublue maintains a set of scripts and container images available at [ublue-akmod](https://github.com/ublue-os/akmods). These images include the necessary scripts to install multiple kernel drivers within the container (Nvidia, OpenRazer, Framework...). The documentation provides guidance on how to properly integrate these drivers into your container image. - -## 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/) -- [Amy OS](https://github.com/astrovm/amyos) -- [VeneOS](https://github.com/Venefilyn/veneos) -- cgit v1.2.3 From 42a6ff3286804854c1c21a7e62158f09e19a9b09 Mon Sep 17 00:00:00 2001 From: tranch Date: Sun, 12 Jul 2026 23:33:44 +0800 Subject: Add live installer build workflow Add a Bazzite-style installer payload, CI workflow, and local\nPodman commands for building and testing the live ISO.\n\nFix stale disk image configuration references and installer targets. --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index fdd7c76..0fc3ba4 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ By focusing strictly on file overlays and configuration writing, this build inte To build AeroCore OS locally, edit `image-template.env` to match your target configurations and then run: ```bash -just build +sudo just build ``` @@ -35,3 +35,16 @@ To test a different upstream base image directly without modifying the environme BASE_IMAGE=ghcr.io/ublue-os/bazzite-deck:testing just build ``` + +To build the Bazzite-style live installer locally, first build the AeroCore +image and then run: + +```bash +sudo just build +just build-live-installer +just run-live-installer +``` + +This requires privileged Podman, a rootful Podman API socket, and roughly +70 GiB of free space. The live installer workflow consumes the published +`latest` AeroCore image and uploads the ISO as a GitHub Actions artifact. -- cgit v1.2.3 From 5a41b4c5daf60b45105d0dc552c4d46022c92b04 Mon Sep 17 00:00:00 2001 From: tranch Date: Wed, 15 Jul 2026 14:04:06 +0800 Subject: Integrate Instruments release seed Download and verify the selected release during image builds. Bootstrap it once into the first graphical user's XDG directories. --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 0fc3ba4..3fc11c5 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,25 @@ FROM ghcr.io/ublue-os/bazzite-deck:stable By focusing strictly on file overlays and configuration writing, this build intentionally avoids invasive operations like `dnf5 install/remove`, COPR enablement, akmods pulls, or kernel recompilations. This architectural choice keeps AeroCore OS completely immune to Fedora/COPR dependency drift during major upstream transition windows (e.g., Bazzite 43 to 44). +## AeroCore Booster integration + +Image builds download the selected AeroCore Booster release from +`AeroCore-IO/booster-installer`, verify its published SHA-256 checksum, and +store the complete release seed under `/usr/share/aerocore-booster-release`. +The release installer runs once for the first active graphical user and copies +the application into that user's XDG directories. After bootstrapping, updates +and uninstallation remain owned by the normal Instruments user-space installer. +The bootstrap completion marker is stored at +`/var/lib/aerocore/instruments-bootstrap-complete`, so uninstalling the user +application does not cause the image seed to reinstall it on the next boot. +Remove that marker and enable `aerocore-instruments-setup.service` to explicitly +bootstrap the application again. + +Set `INSTRUMENTS_VERSION` to a release tag for reproducible builds, or leave it +as `latest` for rolling development images. Set `INSTRUMENTS_ENABLED=false` to +build without Booster. The release repository and API base can be overridden +with `INSTRUMENTS_RELEASE_REPOSITORY` and `INSTRUMENTS_RELEASE_API_BASE`. + --- ## Key Features & Optimizations -- cgit v1.2.3 From 4dd41315acaa07112864a3833dfb7775d9b44274 Mon Sep 17 00:00:00 2001 From: tranch Date: Fri, 24 Jul 2026 17:29:04 +0800 Subject: Rename live installer to installer ISO Use installer ISO terminology across Just, workflows, scripts, docs, and image payloads while preserving compatibility aliases for existing commands. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 3fc11c5..de33959 100644 --- a/README.md +++ b/README.md @@ -55,15 +55,15 @@ BASE_IMAGE=ghcr.io/ublue-os/bazzite-deck:testing just build ``` -To build the Bazzite-style live installer locally, first build the AeroCore +To build the Bazzite-style installer ISO locally, first build the AeroCore image and then run: ```bash sudo just build -just build-live-installer -just run-live-installer +just build-installer-iso +just run-installer-iso ``` This requires privileged Podman, a rootful Podman API socket, and roughly -70 GiB of free space. The live installer workflow consumes the published +70 GiB of free space. The installer ISO workflow consumes the published `latest` AeroCore image and uploads the ISO as a GitHub Actions artifact. -- cgit v1.2.3 From 2d1118b6860c0e80ccc78883d6b814d73df4da67 Mon Sep 17 00:00:00 2001 From: tranch Date: Wed, 29 Jul 2026 14:50:10 +0800 Subject: Align local installer ISO build with CI Use the pinned Titanoboa builder and matching build arguments so just build-installer-iso produces the same media as the GitHub Actions workflow. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index de33959..6faf2ae 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,7 @@ just build-installer-iso just run-installer-iso ``` -This requires privileged Podman, a rootful Podman API socket, and roughly -70 GiB of free space. The installer ISO workflow consumes the published -`latest` AeroCore image and uploads the ISO as a GitHub Actions artifact. +This requires privileged Podman, a rootful Podman API socket, `git`, and +roughly 70 GiB of free space. Local ISO generation uses the same pinned +Titanoboa builder as the installer workflow, and writes the ISO plus its +SHA-256 checksum under `output/`. -- cgit v1.2.3 From 636dcb9dc7af0c23bddeb855da8479eb06df090a Mon Sep 17 00:00:00 2001 From: tranch Date: Wed, 5 Aug 2026 06:50:26 +0800 Subject: Align ISO workflow live naming Match Bazzite's live ISO workflow label and output filename while keeping local build and run helpers pointed at the same artifact. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 6faf2ae..213e029 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ BASE_IMAGE=ghcr.io/ublue-os/bazzite-deck:testing just build ``` -To build the Bazzite-style installer ISO locally, first build the AeroCore +To build the Bazzite-style live ISO locally, first build the AeroCore image and then run: ```bash @@ -66,5 +66,5 @@ just run-installer-iso This requires privileged Podman, a rootful Podman API socket, `git`, and roughly 70 GiB of free space. Local ISO generation uses the same pinned -Titanoboa builder as the installer workflow, and writes the ISO plus its +Titanoboa builder as the live ISO workflow, and writes the ISO plus its SHA-256 checksum under `output/`. -- cgit v1.2.3 From 10411b5e32b78f57b6ad995c434cfc4fc390d689 Mon Sep 17 00:00:00 2001 From: tranch Date: Wed, 26 Aug 2026 10:59:21 +0800 Subject: fix(config): make local dotenv optional Load a private .env when present, but keep CI configuration in GitHub runtime variables and retain the tracked template as a guide. --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 213e029..ac56ad9 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,19 @@ with `INSTRUMENTS_RELEASE_REPOSITORY` and `INSTRUMENTS_RELEASE_API_BASE`. ## Local Build -To build AeroCore OS locally, edit `image-template.env` to match your target configurations and then run: +To build AeroCore OS locally, you may create a private `.env` from the +committed template and edit it to match your target configuration: ```bash -sudo just build - +cp image-template.env .env +# edit .env ``` +`.env` is ignored by Git and optional. When it is absent, Just reads the +required values from the runtime environment. Variables supplied by the shell +or CI environment override matching values in `.env`, so you can test a +different upstream base without changing files. + To test a different upstream base image directly without modifying the environment files: ```bash -- cgit v1.2.3