87 lines
3.2 KiB
Markdown
87 lines
3.2 KiB
Markdown
# image-template
|
|
|
|
# Purpose
|
|
|
|
This repository is meant to be a template for building your own custom Universal Blue image.
|
|
|
|
# Prerequisites
|
|
|
|
Working knowledge in the following topics:
|
|
|
|
- Containers
|
|
- https://www.youtube.com/watch?v=SnSH8Ht3MIc
|
|
- https://www.mankier.com/5/Containerfile
|
|
- bootc
|
|
- https://containers.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
|
|
|
|
# How to Use
|
|
|
|
## Template
|
|
|
|
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
|
|
|
|
The top line is the base image you want to start FROM. Any valid image can be a starting point, examples include:
|
|
|
|
`FROM ghcr.io/ublue-os/bazzite:latest`
|
|
`FROM ghcr.io/ublue-os/bluefin:stable`
|
|
`FROM ghcr.io/ublue-os/aurora-dx:stable`
|
|
|
|
## "Empty" base images
|
|
|
|
These contain a base system WITHOUT a pre-existing desktop. This is recommended for a more bottom up approach or if you want to to use a different desktop environment than is currently available:
|
|
|
|
`FROM ghcr.io/ublue-os/base-main:latest`
|
|
|
|
Use `base-nvidia:latest` if you need the Nvidia drivers. You can also lock to a specific version like `base-nvidia:41`, etc.
|
|
|
|
## 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.
|
|
|
|
#### 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
|
|
|
|
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:
|
|
|
|
|
|
- (CLI instructions) If you have the `github-cli` installed, run:
|
|
|
|
```bash
|
|
gh secret set SIGNING_SECRET < cosign.key
|
|
```
|
|
|
|
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/)
|