From e7824c0426ff9a85a53a1915cf971c9ce6e64542 Mon Sep 17 00:00:00 2001 From: xyny <60004820+xynydev@users.noreply.github.com> Date: Sun, 25 Feb 2024 16:51:55 +0000 Subject: [PATCH] refactor: migration PR (#245) * chore: remove/replace old ublue/startingpoint mentions * chore: replace startingpoint in build badge url * chore: bring up-to-date with the main template, strip cruft from readmes * build(deps): bump mikefarah/yq from 4.40.5 to 4.41.1 (#246) Bumps [mikefarah/yq](https://github.com/mikefarah/yq) from 4.40.5 to 4.41.1. - [Release notes](https://github.com/mikefarah/yq/releases) - [Changelog](https://github.com/mikefarah/yq/blob/master/release_notes.txt) - [Commits](https://github.com/mikefarah/yq/compare/v4.40.5...v4.41.1) --- updated-dependencies: - dependency-name: mikefarah/yq dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * fix: backport some fixes from cli exports to build.sh * docs: add verification message --------- Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/CODEOWNERS | 2 +- .github/semantic.yml | 2 - .github/workflows/build.yml | 2 +- .github/workflows/release-iso.yml | 13 +- CODE_OF_CONDUCT.md | 128 ---------------- CONTRIBUTING.md | 141 ------------------ Containerfile | 2 +- README.md | 77 ++-------- boot_menu.yml | 4 +- build.sh | 4 +- config/README.md | 56 ------- config/files/usr/.gitkeep | 0 .../usr/share/ublue-os/just/100-bling.just | 2 - .../usr/share/ublue-os/just/60-custom.just | 2 - config/recipe.yml | 44 +++--- config/scripts/signing.sh | 30 ---- modules/.gitkeep | 0 modules/README.md | 46 ------ 18 files changed, 44 insertions(+), 511 deletions(-) delete mode 100644 .github/semantic.yml delete mode 100644 CODE_OF_CONDUCT.md delete mode 100644 CONTRIBUTING.md delete mode 100644 config/README.md create mode 100644 config/files/usr/.gitkeep delete mode 100644 config/files/usr/share/ublue-os/just/100-bling.just delete mode 100644 config/files/usr/share/ublue-os/just/60-custom.just delete mode 100644 config/scripts/signing.sh create mode 100644 modules/.gitkeep delete mode 100644 modules/README.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f6a87d27..dc5d1187 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1 @@ -* @castrojo +* @xynydev diff --git a/.github/semantic.yml b/.github/semantic.yml deleted file mode 100644 index b5161df9..00000000 --- a/.github/semantic.yml +++ /dev/null @@ -1,2 +0,0 @@ -enabled: true -titleOnly: true diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index cbba797f..2b8be382 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -70,7 +70,7 @@ jobs: fi - name: Add yq (for reading recipe.yml) - uses: mikefarah/yq@v4.40.5 + uses: mikefarah/yq@v4.41.1 - name: Gather image data from recipe run: | diff --git a/.github/workflows/release-iso.yml b/.github/workflows/release-iso.yml index 899f934c..c89ea274 100644 --- a/.github/workflows/release-iso.yml +++ b/.github/workflows/release-iso.yml @@ -1,8 +1,8 @@ on: push: paths: - - 'boot_menu.yml' - - '.github/workflows/release-iso.yml' + - "boot_menu.yml" + - ".github/workflows/release-iso.yml" workflow_dispatch: name: release-iso @@ -12,13 +12,13 @@ jobs: runs-on: ubuntu-latest permissions: contents: write - container: + container: image: fedora:39 options: --privileged steps: - uses: actions/checkout@v4 - - name: Generate ISO - uses: ublue-os/isogenerator@v2.3.1 + - name: Generate ISO + uses: ublue-os/isogenerator-old@v2.3.1 id: isogenerator with: image-name: ${{ github.event.repository.name }} @@ -43,5 +43,4 @@ jobs: - name: Upload SHA256SUM env: GITHUB_TOKEN: ${{ github.token }} - run: - gh release upload auto-iso ${{ steps.isogenerator.outputs.sha256sum-path }} -R ${{ github.repository_owner }}/${{ github.event.repository.name }} --clobber + run: gh release upload auto-iso ${{ steps.isogenerator.outputs.sha256sum-path }} -R ${{ github.repository_owner }}/${{ github.event.repository.name }} --clobber diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 1b6545af..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,128 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the - overall community - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or - advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email - address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -jorge.castro@gmail.com. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series -of actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -Community Impact Guidelines were inspired by [Mozilla's code of conduct -enforcement ladder](https://github.com/mozilla/diversity). - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 9289907c..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,141 +0,0 @@ -# Welcome to Universal Blue - -Thanks for taking the time to look into helping out! -All contributions are appreciated! -Please refer to our [Code of Conduct](/CODE_OF_CONDUCT.md) while you're at it! - -Feel free to report issues as you find them, and [helping others in the discussions]() is always appreciated. - -# Contributing - -All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. - -> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: -> - Star the project -> - Tweet about it -> - Refer this project in your project's readme -> - Mention the project at local meetups and tell your friends/colleagues - -## Table of Contents - -- [Code of Conduct](#code-of-conduct) -- [I Have a Question](#i-have-a-question) -- [I Want To Contribute](#i-want-to-contribute) -- [Reporting Bugs](#reporting-bugs) -- [How to test incoming changes](#how-to-test-incoming-changes) -- [Building Locally](#building-locally) -- [Styleguides](#styleguides) -- [Commit Messages](#commit-messages) -- [Join The Project Team](#join-the-project-team) - -## Code of Conduct - -This project and everyone participating in it is governed by the -[CONTRIBUTING.md Code of Conduct](/CODE_OF_CONDUCT.md). -By participating, you are expected to uphold this code. Please report unacceptable behavior -to jorge.castro@gmail.com - -## I Have a Question - -> If you want to ask a question, ask in the [discussion forum](https://github.com/orgs/ublue-os/discussions) - -## I Want To Contribute - -> ### Legal Notice -> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. - -Generally speaking we try to follow the [Lazy Concensus](http://lazyconcens.us/) model of development to keep the builds healthy and ourselves happy. - - If you're looking for concensus to make a decision post an issue for feedback and remember to account for timezones and weekends/holidays/work time. - - We want people to be opinionated in their builds so we're more of a loose confederation of repos than a top-down org. - - Try not to merge your own stuff, ask for a review. At some point when we have enough reviewers we'll be turning on branch protection. - -### Reporting Bugs - -#### Before Submitting a Bug Report - -A good bug report should describe the issue in detail. Generally speaking: - -- Make sure that you are using the latest version. -- Remember that these are unofficial builds, it's usually prudent to investigate an issue before reporting it here or in Fedora! -- Collect information about the bug: - - `rpm-ostree status -v` usually helps -- Image and Version -- Possibly your input and the output -- Can you reliably reproduce the issue? And can you also reproduce it with older versions? - -### How to test incoming changes - -One of the nice things about the image model is that we can generate an entire OS image for every change we want to commit, so this makes testing way easier than in the past. You can rebase to it, see if it works, and then move back. This also means we can increase the amount of testers! - -We strive towards a model where proposed changes are more thoroughly reviewed and tested by the community. So here's how to do it. If you see a pull request that is opened up on an image you're following you can leave a review on how it's working for you. At the bottom of every PR you'll see something like this: - -![image](https://user-images.githubusercontent.com/1264109/221305388-3860fc07-212c-4eb9-80d9-5d7a35a77f46.png) - -Click on "Add your review", and then you'll see this: - -![image](https://user-images.githubusercontent.com/1264109/221307636-5e312e48-821f-4206-848f-7fbc2c91cd78.png) - -Don't worry, you can't mess anything up, all the merging and stuff will be done by the maintainer, what this does is lets us gather information in a more formal manner than just shoving everything in a forum thread. The more people are reviewing and testing images, the better off we'll be, especially for images that are new like Sericea. - -At some point we'll have a bot that will leave you instructions on how to rebase to the image and all that stuff, but in the meantime we'll leave instructions manually. - -Here's an example: https://github.com/ublue-os/nvidia/pull/49 - -## Building Locally - -The minimum tools required are git and a working machine with podman enabled and configured. -Building locally is much faster than building in GitHub and is a good way to move fast before pushing to a remote. - -### Clone the repo you want - - git clone https://github.com/ublue-os/base.git - -### Build the image - -First make sure you can build an existing image: - - podman build . -t something - -Then confirm your image built: - - podman image ls - -TODO: Set up and push to your own local registry - -### Make your changes - -This usually involved editing the `Containerfile`. Most techniques for building containers apply here, if you're new to containers using the term "Dockerfile" in your searches usually shows more results when you're searching for information. - -Check out CoreOS's [layering examples](https://github.com/coreos/layering-examples) for more information on customizing. - -### Reporting problems to Fedora - -We endevaour to be a good partner for Fedora. - -This project is consuming new features in Fedora and ostree, it is not uncommon to find an issue. -Issues should be reported upstream, and in some cases we can help test and find fixes. -Some of the issues you find may involve other dependencies in other projects, in those cases the Fedora team will tell you where to report the issue. - -Upstream bug tracker: [https://github.com/fedora-silverblue/issue-tracker/issues](https://github.com/fedora-silverblue/issue-tracker/issues) - -## Styleguides -### Commit Messages - -We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and enforce them with a bot to keep the changelogs tidy: - -``` -chore: add Oyster build script -docs: explain hat wobble -feat: add beta sequence -fix: remove broken confirmation message -refactor: share logic between 4d3d3d3 and flarhgunnstow -style: convert tabs to spaces -test: ensure Tayne retains clothing -``` - -## Join The Project Team - -If you're interested in _maintaining_ something then let us know! - -## Attribution -This guide is based on the **contributing.md**. [Make your own](https://contributing.md/)! diff --git a/Containerfile b/Containerfile index b89ff336..0c013469 100644 --- a/Containerfile +++ b/Containerfile @@ -28,7 +28,7 @@ COPY config /tmp/config/ # Copy modules # The default modules are inside ublue-os/bling -COPY --from=ghcr.io/ublue-os/bling:latest /modules /tmp/modules/ +COPY --from=ghcr.io/blue-build/modules:latest /modules /tmp/modules/ # Custom modules overwrite defaults COPY modules /tmp/modules/ diff --git a/README.md b/README.md index 2feeef90..55e7499a 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,19 @@ -# Starting point +# Legacy template [![build-ublue](https://github.com/blue-build/legacy-template/actions/workflows/build.yml/badge.svg)](https://github.com/blue-build/legacy-template/actions/workflows/build.yml) -> **Warning** -> Startingpoint was recently rewritten, and this version is considered a "1.0" *semi-*stable release. -> There are breaking changes between this and the previous version. -> If you are merging changes from the previous (v0) version, please refer to [the heads-up blog post](https://universal-blue.org/blog/2023/09/02/startingpoint-rewrite-heads-up-what-you-need-to-know/). - -[![build-ublue](https://github.com/ublue-os/startingpoint/actions/workflows/build.yml/badge.svg)](https://github.com/ublue-os/startingpoint/actions/workflows/build.yml) - -This is a constantly updating template repository for creating [a native container image](https://fedoraproject.org/wiki/Changes/OstreeNativeContainerStable) designed to be customized however you want. GitHub will build your image for you, and then host it for you on [ghcr.io](https://github.com/features/packages). You then just tell your computer to boot off of that image. GitHub keeps 90 days worth image backups for you, thanks Microsoft! - -For more info, check out the [uBlue homepage](https://universal-blue.org/) and the [main uBlue repo](https://github.com/ublue-os/main/) - -## Getting started - -See the [Make Your Own-page in the documentation](https://universal-blue.org/tinker/make-your-own/) for quick setup instructions for setting up your own repository based on this template. - -Don't worry, it only requires some basic knowledge about using the terminal and git. - -After setup, it is recommended you update this README to describe your custom image. - -> **Note** -> Everywhere in this repository, make sure to replace `ublue-os/startingpoint` with the details of your own repository. Unless you used one of the automatic repository setup tools in which case the previous repo identifier should already be your repo's details. - -> **Warning** -> To start, you *must* create a branch called `live` which is exclusively for your customizations. That is the **only** branch the GitHub workflow will deploy to your container registry. Don't make any changes to the original "template" branch. It should remain untouched. By using this branch structure, you ensure a clear separation between your own "published image" branch, your development branches, and the original upstream "template" branch. Periodically sync and fast-forward the upstream "template" branch to the most recent revision. Then, simply rebase your `live` branch onto the updated template to effortlessly incorporate the latest improvements into your own repository, without the need for any messy, manual "merge commits". - -## Customization - -The easiest way to start customizing is by looking at and modifying `config/recipe.yml`. It's documented using comments and should be pretty easy to understand. - -If you want to add custom configuration files, you can just add them in the `/usr/etc/` directory, which is the official OSTree "configuration template" directory and will be applied to `/etc/` on boot. `config/files/usr` is copied into your image's `/usr` by default. If you need to add other directories in the root of your image, that can be done using the `files` module. Writing to `/var/` in the image builds of OSTree-based distros isn't supported and will not work, as that is a local user-managed directory! - -For more information about customization, see [the README in the config directory](config/README.md) - -Documentation around making custom images exists / should be written in two separate places: -* [The Tinkerer's Guide on the website](https://universal-blue.org/tinker/make-your-own/) for general documentation around making custom images, best practices, tutorials, and so on. -* Inside this repository for documentation specific to the ins and outs of the template (like module documentation), and just some essential guidance on how to make custom images. +> **Warning** +> This repository was previously `ublue-os/startingpoint`, but has now been [moved to the BlueBuild organization](https://blue-build.org/blog/introducing-bluebuild/). New custom images should be created from the new [blue-build/template](https://github.com/blue-build/template), but this repository will be supported for the foreseeable future. +> Check out the [migration guide](https://blue-build.org/blog/introducing-bluebuild/#how-to-migrate) for migration instructions. ## Installation -> **Warning** -> [This is an experimental feature](https://www.fedoraproject.org/wiki/Changes/OstreeNativeContainerStable) and should not be used in production, try it in a VM for a while! +> **Warning** +> [This is an experimental feature](https://www.fedoraproject.org/wiki/Changes/OstreeNativeContainerStable), try at your own discretion. To rebase an existing Silverblue/Kinoite installation to the latest build: - First rebase to the unsigned image, to get the proper signing keys and policies installed: ``` - rpm-ostree rebase ostree-unverified-registry:ghcr.io/ublue-os/startingpoint:latest + rpm-ostree rebase ostree-unverified-registry:ghcr.io/blue-build/legacy-template:latest ``` - Reboot to complete the rebase: ``` @@ -54,45 +21,29 @@ To rebase an existing Silverblue/Kinoite installation to the latest build: ``` - Then rebase to the signed image, like so: ``` - rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/startingpoint:latest + rpm-ostree rebase ostree-image-signed:docker://ghcr.io/blue-build/legacy-template:latest ``` - Reboot again to complete the installation ``` systemctl reboot ``` -This repository builds date tags as well, so if you want to rebase to a particular day's build: - -``` -rpm-ostree rebase ostree-image-signed:docker://ghcr.io/ublue-os/startingpoint:20230403 -``` - -This repository by default also supports signing. - The `latest` tag will automatically point to the latest build. That build will still always use the Fedora version specified in `recipe.yml`, so you won't get accidentally updated to the next major version. ## ISO -This template includes a simple Github Action to build and release an ISO of your image. +This template includes a simple Github Action to build and release an ISO of your image. To run the action, simply edit the `boot_menu.yml` by changing all the references to startingpoint to your repository. This should trigger the action automatically. -The Action uses [isogenerator](https://github.com/ublue-os/isogenerator) and works in a similar manner to the official Universal Blue ISO. If you have any issues, you should first check [the documentation page on installation](https://universal-blue.org/installation/). The ISO is a netinstaller and should always pull the latest version of your image. +The Action currently uses [ublue-os/isogenerator-old](https://github.com/ublue-os/isogenerator-old) and works in a similar manner to the official Universal Blue ISO. If you have any issues, you should first check [the documentation page on installation](https://universal-blue.org/installation/). The ISO is a netinstaller and should always pull the latest version of your image. Note that this release-iso action is not a replacement for a full-blown release automation like [release-please](https://github.com/googleapis/release-please). -## `just` +## Verification -The [`just`](https://just.systems/) command runner is included in all `ublue-os/main`-derived images. +These images are signed with [Sigstore](https://www.sigstore.dev/)'s [cosign](https://github.com/sigstore/cosign). You can verify the signature by downloading the `cosign.pub` file from this repo and running the following command: -You need to have a `~/.justfile` with the following contents and `just` aliased to `just --unstable` (default in posix-compatible shells on ublue) to get started with just locally. -``` -!include /usr/share/ublue-os/just/main.just -!include /usr/share/ublue-os/just/nvidia.just -!include /usr/share/ublue-os/just/custom.just +```bash +cosign verify --key cosign.pub ghcr.io/blue-build/legacy-template ``` -Then type `just` to list the just recipes available. - -The file `/usr/share/ublue-os/just/custom.just` is intended for the custom just commands (recipes) you wish to include in your image. By default, it includes the justfiles from [`ublue-os/bling`](https://github.com/ublue-os/bling), if you wish to disable that, you need to just remove the line that includes bling.just. - -See [the just-page in the Universal Blue documentation](https://universal-blue.org/guide/just/) for more information. diff --git a/boot_menu.yml b/boot_menu.yml index 7a272cc5..81b449fb 100644 --- a/boot_menu.yml +++ b/boot_menu.yml @@ -1,5 +1,5 @@ ublue_variants: - - label: ublue-os/startingpoint + - label: blue-build/legacy-template ks: /kickstart/ublue-os.ks flavors: - - label: startingpoint \ No newline at end of file + - label: legacy-template diff --git a/build.sh b/build.sh index c48b2ae5..9e133d3e 100644 --- a/build.sh +++ b/build.sh @@ -6,7 +6,7 @@ # Editing this file directly is an unsupported configuration. # Tell build process to exit if there are any errors. -set -oue pipefail +set -euo pipefail export CONFIG_DIRECTORY="/tmp/config" RECIPE_FILE="$CONFIG_DIRECTORY/$RECIPE" @@ -15,7 +15,7 @@ export MODULE_DIRECTORY="/tmp/modules" # https://mikefarah.gitbook.io/yq/usage/tips-and-tricks#yq-in-a-bash-loop get_yaml_array() { # creates array $1 with content at key $2 from $3 - readarray "$1" < <(echo "$3" | yq -I=0 "$2") + readarray -t "$1" < <(echo "$3" | yq -I=0 "$2") } export -f get_yaml_array # this makes the function available to all modules diff --git a/config/README.md b/config/README.md deleted file mode 100644 index 53892ed4..00000000 --- a/config/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Configuring your image - -The main file of your is *the recipe file*. You can have multiple recipe files, and the ones to build are declared in the matrix section of [build.yml](../.github/workflows/build.yml). - -## Basic options - -At the top of the recipe, there are four *mandatory* configuration options. - -`name:` is the name of the image that is used when rebasing to it. For example, the name "sapphire" would result in the final URL of the container being `ghcr.io//sapphire`. - -`description:` is a short description of your image that will be attached to your image's metadata. - -`base-image:` is the URL of the image your image will be built upon. - -`image-version:` is the version tag of the `base-image` that will be pulled. For example, Universal Blue's images build with Fedora version tags (`38`, `39`), with the `latest` tag for the latest major version, and [many other tags](https://github.com/ublue-os/main/pkgs/container/base-main/versions?filters%5Bversion_type%5D=tagged). - -## Modules - -The core of startingpoint's configuration is built around the idea of modules. Modules are scripts in the [`../modules`](../modules/) directory that you configure under `modules:` in the recipe. They are executed in order, and can run arbitrary shell commands and write any files. - -This repository fetches some useful default modules from [`ublue-os/bling`](https://github.com/ublue-os/bling/), like [`rpm-ostree`](https://universal-blue.org/tinker/modules/rpm-ostree) for pseudo-declarative package management, [`bling`](https://universal-blue.org/tinker/modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](https://universal-blue.org/tinker/modules/files) for copying files from the `config/files/` directory into your image. - -For a comprehensive list of modules, their in-depth documentation and example configuration, check out [the Modules page on the website](https://universal-blue.org/tinker/modules/). - -### Building multiple images and including module configuration from other files - -To build multiple images, you need to create another recipe.yml file, which you should name based on what kind of image you want it to build. Then, edit the [`build.yml`](../.github/workflows/build.yml) file. Inside the file, under `jobs: strategy: matrix:`, there's a list of recipe files to build images, which you need to add your new recipe file to. These should be paths to files inside the `config` directory. - -Module configuration can be included from other files using the `from-file` syntax. The value should be a path to a file inside the `config` directory. For example, the following snippet could be used to include the configuration for installing a set of packages common to multiple images. -```yaml -modules: - - from-file: common-packages.yml -``` -And inside config/common-packages.yml -```yaml -type: rpm-ostree -install: - - i3 - - dunst - - rofi - - kitty -``` -An external module can also include multiple modules. -```yaml -# config/common.yml -modules: - - type: files - files: - - usr: /usr - - type: rpm-ostree - install: - - i3 - - dunst - - rofi - - kitty -``` diff --git a/config/files/usr/.gitkeep b/config/files/usr/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/config/files/usr/share/ublue-os/just/100-bling.just b/config/files/usr/share/ublue-os/just/100-bling.just deleted file mode 100644 index 9e3a89ba..00000000 --- a/config/files/usr/share/ublue-os/just/100-bling.just +++ /dev/null @@ -1,2 +0,0 @@ -# this file is a placeholder, -# making changes here is not supported diff --git a/config/files/usr/share/ublue-os/just/60-custom.just b/config/files/usr/share/ublue-os/just/60-custom.just deleted file mode 100644 index 9fbf4928..00000000 --- a/config/files/usr/share/ublue-os/just/60-custom.just +++ /dev/null @@ -1,2 +0,0 @@ -import '100-bling.just' -# Include some of your custom scripts here! diff --git a/config/recipe.yml b/config/recipe.yml index cc14c1ba..7ce393ee 100644 --- a/config/recipe.yml +++ b/config/recipe.yml @@ -1,7 +1,7 @@ # image will be published to ghcr.io// -name: startingpoint +name: template # description will be included in the image's metadata -description: A starting point for further customization of uBlue images. Make your own! https://ublue.it/making-your-own/ +description: This is my personal OS image. # the base image to build on top of (FROM) and the version tag to use base-image: ghcr.io/ublue-os/silverblue-main @@ -12,13 +12,10 @@ image-version: 39 # latest is also supported if you want new updates ASAP modules: - type: files files: - - usr: /usr # copy static configurations - # - # copies config/files/usr into your image's /usr - # - # configuration you wish to end up in /etc/ on the booted system - # should be added into /usr/etc/ as that is the proper "distro" - # config directory on ostree. Read more in the files module's README + - usr: + /usr # copies config/files/usr into your image's /usr. + # put configuration files you want in /etc/ on a booted system + # in /usr/etc/ in the image. read more in files module reference. - type: rpm-ostree repos: @@ -31,28 +28,21 @@ modules: - firefox-langpacks # langpacks needs to also be removed to prevent dependency problems - type: default-flatpaks - notify: true # Send notification after install/uninstall is finished (true/false) + notify: true # Send notification after install/uninstall is finished (true/false) system: # If no repo information is specified, Flathub will be used by default - repo-url: https://dl.flathub.org/repo/flathub.flatpakrepo - repo-name: flathub + # repo-url: https://dl.flathub.org/repo/flathub.flatpakrepo + # repo-name: flathub # repo-title: "Flathub (system-wide)" # Optional; this sets the remote's user-facing name in graphical frontends like GNOME Software install: - # - org.gnome.Loupe - # - one.ablaze.floorp//lightning # This is an example of flatpak which has multiple branches in selection (flatpak//branch). - # Flatpak runtimes are not supported (like org.winehq.Wine//stable-23.08). - # Only normal flatpak applications are (like Floorp Lightning web browser in this example). - # Multiple install of same flatpaks with different branches is not supported. + - org.mozilla.firefox + # - org.gnome.Loupe + # - one.ablaze.floorp//lightning # This is an example of flatpak which has multiple branches in selection (flatpak//branch). + # Flatpak runtimes are not supported (like org.winehq.Wine//stable-23.08), + # only normal flatpak applications are (like Floorp Lightning web browser in this example). + # Installing different branches of the same Flatpak is not supported. remove: # - org.gnome.eog - # - # A flatpak repo can also be added without having to install flatpaks, - # as long as one of the repo- fields is present - user: - repo-url: https://dl.flathub.org/repo/flathub.flatpakrepo - repo-name: flathub - - type: script - scripts: - # this sets up the proper policy & signing files for signed images to work - - signing.sh + - type: signing # this sets up the proper policy & signing files for signed images to work fully + diff --git a/config/scripts/signing.sh b/config/scripts/signing.sh deleted file mode 100644 index 16b0ea85..00000000 --- a/config/scripts/signing.sh +++ /dev/null @@ -1,30 +0,0 @@ -#!/usr/bin/env bash - -# Tell build process to exit if there are any errors. -set -oue pipefail - -echo "Setting up container signing in policy.json and cosign.yaml for $IMAGE_NAME" -echo "Registry to write: $IMAGE_REGISTRY" - -cp /usr/share/ublue-os/cosign.pub /usr/etc/pki/containers/"$IMAGE_NAME".pub - -FILE=/usr/etc/containers/policy.json - -yq -i -o=j '.transports.docker |= - {"'"$IMAGE_REGISTRY"'/'"$IMAGE_NAME"'": [ - { - "type": "sigstoreSigned", - "keyPath": "/usr/etc/pki/containers/'"$IMAGE_NAME"'.pub", - "signedIdentity": { - "type": "matchRepository" - } - } - ] - } -+ .' "$FILE" - -IMAGE_REF="ostree-image-signed:docker://$IMAGE_REGISTRY/$IMAGE_NAME" -printf '{\n"image-ref": "'"$IMAGE_REF"'",\n"image-tag": "latest"\n}' > /usr/share/ublue-os/image-info.json - -cp /usr/etc/containers/registries.d/ublue-os.yaml /usr/etc/containers/registries.d/"$IMAGE_NAME".yaml -sed -i "s ghcr.io/ublue-os $IMAGE_REGISTRY g" /usr/etc/containers/registries.d/"$IMAGE_NAME".yaml diff --git a/modules/.gitkeep b/modules/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/modules/README.md b/modules/README.md deleted file mode 100644 index 40a8bc8f..00000000 --- a/modules/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Making modules - -If you want to extend Startingpoint with custom functionality that requires configuration, you should create a module. Modules are scripts in the subdirectories of this directory. The `type:` key in the recipe.yml should be used as both the name of the folder and script, with the script having an additional `.sh` suffix. Creating a custom module with the same name as a default module will override it. - -Each module intended for public usage should include a `README.md` file inside it's directory with a short description of the module and documentation for each configuration option. - -Modules get only the configuration options given to them in the recipe.yml, not the configuration of other modules or any top-level keys. The configuration is given as the first argument as a single-line json string. You can check out the default modules for examples on how to parse such string using `yq` or `jq`. - -Additionally, each module has access to four environment variables, `CONFIG_DIRECTORY` pointing to the directory containing the confiuration files for the build (`/tmp/config`), `IMAGE_NAME` being the name of the image as declared in the recipe, `BASE_IMAGE` being the URL of the container image used as the base (FROM) in the image, and `OS_VERSION` being the `VERSION_ID` from `/usr/lib/os-release`. - -When running modules, the working directory is the `CONFIG_DIRECTORY`. - -A helper bash function called `get_yaml_array` is exported from the main build script. -```bash -# "$1" is the first cli argument, being the module configuration. -# If you need to read from some other JSON string, just replace "$1" with "$VARNAME". -get_yaml_array OUTPUT_VAR_NAME '.yq.key.to.array[]' "$1" -for THING in "${OUTPUT_VAR_NAME[@]}"; do - echo "$THING" -done -``` - -All bash-based modules should start with the following lines to ensure the image builds fail on errors, and that the correct shell is used to run them. -```bash -#!/usr/bin/env bash -set -oue pipefail -``` - -## Style directions for official modules - -These are general directions for writing official modules and their documentation to follow to keep a consistent style. Not all of these are to be mindlessly followed, especially the ones about grammar and writing style. It's good to keep these in mind if you intend to contribute back upstream, though, so that your module doesn't feel out of place. - -### Bash - -- Start with `#!/usr/bin/env bash` and `set -oue pipefail` -- Don't print "===", this is only for encapsulating the output of _different_ modules in `build.sh` -- Print something on each step and on errors for easier debugging -- Use CAPITALIZED names for variables that are read from the configuration - -### README - -- Title should be "`type` Module for Startingpoint", where the name/type of the module is a noun that shows the module's purpose -- There should be a subtitle "Example configuration", under which there should be a loosely documented yaml block showcasing each of the module's configuration options - - For a YAML block, specify the language as "yaml", not "yml" (MkDocs only supports "yaml") -- At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script" -- Use passive grammar when talking about the user, ie. "should be used", "can be configured", preferring references to what the module does, ie. "This module downloads the answer to the question of life, the universe and everything..."