scottk/secureblue
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/secureblue.git synced 2025-11-04 04:18:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: some docs fixes, better formatting, etc

Browse Source
This commit is contained in:
ER
2023-09-09 12:08:20 +03:00
parent b3ddcd8851
commit 15b3d394b8
6 changed files with 33 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
Containerfile
View File

@@ -3,42 +3,39 @@
# Instead of adding RUN statements here, you should consider creating a script
# in `config/scripts/`. Read more in `modules/script/README.md`
# It takes in the recipe, version, and base image as arguments,
# This Containerfile takes in the recipe, version, and base image as arguments,
# all of which are provided by build.yml when doing builds
# in the cloud. The ARGs have default values, but changing those
# does nothing if the image is built in the cloud.
# !! Warning: changing these might not do anything for you. Read comment above.
ARG IMAGE_MAJOR_VERSION=38
# Warning: changing this might not do anything for you. Read comment above.
ARG BASE_IMAGE_URL=ghcr.io/ublue-os/silverblue-main
FROM ${BASE_IMAGE_URL}:${IMAGE_MAJOR_VERSION}
# The default recipe set to the recipe's default filename
# so that `podman build` should just work for many people.
ARG RECIPE=recipe.yml
# The default recipe is set to the recipe's default filename
# so that `podman build` should just work for most people.
ARG RECIPE=recipe.yml
# The default image registry to write to policy.json and cosign.yaml
ARG IMAGE_REGISTRY=ghcr.io/ublue-os
COPY cosign.pub /usr/share/ublue-os/cosign.pub
COPY config /tmp/config
COPY cosign.pub /usr/share/ublue-os/cosign.pub
# Copy the bling from ublue-os/bling into tmp, to be installed later by the bling module
# Feel free to remove these lines if you want to speed up image builds and don't want any bling
COPY --from=ghcr.io/ublue-os/bling:latest /rpms /tmp/bling/rpms
COPY --from=ghcr.io/ublue-os/bling:latest /files /tmp/bling/files
# "yq" used in build.sh and the "setup-flatpaks" just-action to read recipe.yml.
# Copied from the official container image since it's not available as an RPM.
COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq
# Copy build script; this is what parses your recipe
# Copy build scripts & configuration
COPY build.sh /tmp/build.sh
# Copy modules to a temporary directory, they'll only to be executed during the build
COPY modules /tmp/modules/
COPY config /tmp/config/
# `yq` is used for parsing the yaml configuration
# It is copied from the official container image since it's not available as an RPM.
COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq
# Run the build script, then clean up temp files and finalize container build.
RUN chmod +x /tmp/build.sh && /tmp/build.sh && \

4
README.md
View File

@@ -30,12 +30,12 @@ For more information about customization, see [the README in the config director
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, how it works, how to customize it, and some essential guidance on how to make custom images.
* 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.
## Installation
> **Warning**
> This is an experimental feature and should not be used in production, try it in a VM for a while!
> [This is an experimental feature](https://www.fedoraproject.org/wiki/Changes/OstreeNativeContainerStable) and should not be used in production, try it in a VM for a while!
To rebase an existing Silverblue/Kinoite installation to the latest build:

12
config/README.md
View File

@@ -4,7 +4,7 @@ The main file of your is *the recipe file*. You can have multiple recipe files,
## Basic options
At the top of the recipe, there are four mandatory configuration 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/<yourusername>/sapphire`.
@@ -18,7 +18,7 @@ At the top of the recipe, there are four mandatory configuration options.
The core of startingpoint's configuration is built around the idea of modules. Modules are scripts in the [`../modules`](../modules/) directory that you list out under `modules:` in the recipe. They are executed in order, and can run arbitrary shell commands and write any files.
This repository comes with three modules out of the box, [`rpm-ostree`](../modules/rpm-ostree) for pseudo-declarative package management, [`yafti`](../modules/yafti) for installing [yafti](https://github.com/ublue-os/yafti) and easing basic configuration, [`bling`](../modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`script`](../modules/script) for running small custom scripts at the build stage, like pulling in configuration or setting up `rpm-ostree` support for proper signing (see [`signing.sh`](./scripts/signing.sh)).
This repository comes with some modules out of the box, like [`rpm-ostree`](../modules/rpm-ostree) for pseudo-declarative package management, [`bling`](../modules/bling) for pulling extra components from [`ublue-os/bling`](https://github.com/ublue-os/bling), and [`files`](../modules/files) for copying files from the `config/files/` directory into your image.
For more in-depth documentation on each module, check out the README.md files in each module folder.
@@ -34,17 +34,17 @@ modules:
### 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 the [`../modules`](../modules/) 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.
If you want to extend Startingpoint with custom functionality that requires configuration, you should create a module. Modules are scripts in the subdirectories of the [`../modules`](../modules/) 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.
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 startingpoint directory in `/usr/share/ublue-os/`, `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`.
Additionally, each module has access to four environment variables, `CONFIG_DIRECTORY` pointing to the Startingpoint directory in `/usr/share/ublue-os/`, `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`.
A helper bash function called `get_yaml_array` is exported from the main build script. Syntax:
A helper bash function called `get_yaml_array` is exported from the main build script.
```bash
# "$1" read from the first cli argument, being the module configuration.
# "$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

24
config/recipe.yml
View File

@@ -7,21 +7,16 @@ description: A starting point for further customization of uBlue images. Make yo
base-image: ghcr.io/ublue-os/silverblue-main
image-version: 38 # latest is also supported if you want new updates ASAP
# list of modules that will be executed in order
# you can include multiple of the same module
# list of modules, executed in order
# you can include multiple instancesof the same module
modules:
- type: files
files:
- usr: /usr
# Copy static configurations and component files.
# Warning: If you want to place anything in "/etc" of the final image, you MUST
# place them in "./usr/etc" in your repo, so that they're written to "/usr/etc"
# on the final system. That is the proper directory for "system" configuration
# templates on immutable Fedora distros, whereas the normal "/etc" is ONLY meant
# for manual overrides and editing by the machine's admin AFTER installation!
# See issue #28 (https://github.com/ublue-os/startingpoint/issues/28).
- usr: /usr # copy static configurations
# 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
- type: rpm-ostree
repos:
@@ -47,11 +42,10 @@ modules:
- type: yafti # if included, https://github.com/ublue-os/yafti will be installed and set up
custom-flatpaks: # this section is optional
- Celluloid: io.github.celluloid_player.Celluloid
- Krita: org.kde.krita
# - Celluloid: io.github.celluloid_player.Celluloid
# - Krita: org.kde.krita
- type: script
scripts:
# this sets up the proper policy & signing files for signed images to work
- signing.sh

3
modules/README.md Normal file
View File

@@ -0,0 +1,3 @@
# Modules
This directory includes all the different modules for Startingpoint. Refer to the README files inside each module's corresponding directory for in-depth documentation, and the README inside `config/` for more general documentation.

2
modules/files/README.md
View File

@@ -3,7 +3,7 @@
The `files` module simplifies the process of copying files to the image during the build time. These files are sourced from the `config/files` directory, which is located at `/tmp/config/files` inside the image.
> **Warning**
> If you want to place anything in `/etc` of the final image, you MUST place them in `/usr/etc` in your repo, so that they're written to `/usr/etc` on the final system. That is the proper directory for "system" configuration templates on immutable Fedora distros, whereas the normal `/etc` is ONLY meant for manual overrides and editing by the machine's admin AFTER installation! See issue https://github.com/ublue-os/startingpoint/issues/28.
> If you want to place anything in `/etc` of the final image, you MUST place them in `/usr/etc` in your repo, so that they're written to `/usr/etc` on the final system. That is the proper directory for "system" configuration templates on immutable Fedora distros, whereas the normal `/etc` is meant for manual overrides and editing by the machine's admin AFTER installation! See issue https://github.com/ublue-os/startingpoint/issues/28.
## Example Configuration: