Layers
Layers are defined by layer configuration files <layer name>.toml
in the layers
directory. As described in the introduction, a layer is built by executing recipes. For a given layer, the respective layer configuration file specifies the recipes to be executed as well as an optional parent layer that should be used as a base. Here is an example taken from the Debian template:
#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json
parent = "core/debian-bookworm"
recipes = [
# Setup Debian for booting via Grub.
"core/debian-grub-setup",
# Set a static hostname.
"core/set-hostname",
# Persist `/root`.
"core/persist-root-home",
# Setup and enable SSH.
"core/ssh",
# Enable discovery of the system in the local network.
"rugix-extra/avahi",
# Setup the network.
"setup-network",
# Install a static website.
"hello-world",
]
This file defines a layer, named customized
, that is based on the layer core/debian-bookworm
, a general-purpose layer to build Debian-based systems shipped with Rugix Bakery. The configuration file then specifies a bunch of recipes to set up and customize the system, for instance, setting up a bootloader integration with Grub and providing a network configuration.
In addition to project-specific layers and recipes defined in the project directory, you can use layers and recipes provided by repositories. In case of the example, these repositories are core
and rugix-extra
. We will explain repositories in detail later. The core
repository is shipped with Rugix Bakery and includes the following layers for you to use as a parent layer:
core/debian-bookworm
for Debian Bookworm,core/alpine-3-20
for Alpine Linux 3.20,core/raspios-bookworm
for Raspberry Pi OS (Bookworm), andcore/raspios-bullseye
for Raspberry Pi OS (Bullseye).
Root Layers
If you do not want to use a parent layer, you can also start from scratch by omitting the parent
setting and specifying root = true
. For example, here is a layer configuration that bootstraps Debian using the core/debian-bootstrap
recipe:
#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json
root = true
recipes = [
"core/debian-bootstrap",
]
[parameters."core/debian-bootstrap"]
suite = "bookworm"
snapshot = "20240501T024440Z"
By setting the snapshot
parameter of the core/debian-bootstrap
recipe (more on parameters later), the resulting layer will be based on a particular Debian snapshot, thereby leading to a semi-reproducible1 build.
Importing Layers
Rugix Bakery can import layers from external sources. To this end, you can specify a URL.
Here is an example for importing a layer from a Raspberry Pi OS (Bookworm) image:
#:schema https://raw.githubusercontent.com/silitics/rugix/refs/tags/v0.8.0/schemas/rugix-bakery-layer.schema.json
name = "Raspberry Pi OS (Bookworm)"
url = "https://downloads.raspberrypi.com/raspios_lite_arm64/images/raspios_lite_arm64-2024-03-15/2024-03-15-raspios-bookworm-arm64-lite.img.xz"
Rugix Bakery can download images and TAR archives from HTTP URLs and create layers from them. This is useful if one wants to take an existing system image as a basis, e.g., when building a customized variant of Raspberry Pi OS. In addition to HTTP URLs, file URLs starting with file://
are also supported. These URLs are resolved relative to the project directory.
Note that imported layers must not specify any recipes. Customizations are applied by using them as a parent.
Excluding recipes
Recipes may depend on other recipes and as such will pull in their dependencies automatically when specified in the recipes
list of a layer. To avoid that, e.g., when you want to replace some recipe with a local variant, you can exclude certain recipes from a layer. To this end, you can provide a list of recipes to exclude via the exclude
property.