From 2691a36cc9b7af3aa4d75a100d2aead707783675 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 15 May 2024 11:31:00 -0400 Subject: [PATCH] docs/install: A few changes - Emphasize `to-filesystem` more, clarify `to-disk` is more "demo"; we definitely support "external installers" too with `to-filesystem`. - Add machine-local state post-install section Signed-off-by: Colin Walters --- docs/src/bootc-install.md | 46 ++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/docs/src/bootc-install.md b/docs/src/bootc-install.md index b006ee1ee..c29b024dc 100644 --- a/docs/src/bootc-install.md +++ b/docs/src/bootc-install.md @@ -32,17 +32,18 @@ However, nothing *else* (external) is required to perform a basic installation to disk - the container image itself comes with a baseline self-sufficient installer that sets things up ready to boot. -This is motivated by experience gained from the Fedora CoreOS -project where today the expectation is that one boots from a pre-existing disk -image (AMI, qcow2, etc) or uses [coreos-installer](https://github.com/coreos/coreos-installer) -for many bare metal setups. But the problem is that coreos-installer -is oriented to installing raw disk images. This means that if -one creates a custom derived container, then it's required for -one to also generate a raw disk image to install. This is a large -ergonomic hit. - -With the `bootc` install methods, no extra steps are required. Every container -image comes with a basic installer. +## Internal vs external installers + +The `bootc install to-disk` process only sets up a very simple +filesystem layout, using the default filesystem type defined in the container image, +plus hardcoded requisite platform-specific partitions such as the ESP. + +In general, the `to-disk` flow should be considered mainly a "demo" for +the `bootc install to-filesystem` flow, which can be used by "external" installers +today. For example, in the [Fedora/CentOS bootc project](https://docs.fedoraproject.org/en-US/bootc/) +project, there are two "external" installers in Anaconda and `bootc-image-builder`. + +More on this below. ## Executing `bootc install` @@ -98,13 +99,12 @@ the image in `/etc/ostree/auth.json`. Alternatively, the secret can be added after an installation process completes and managed separately; in that case you will need to specify `--skip-fetch-check`. -### Operating system install configuration required +### Configuring the default root filesystem type -The container image **MUST** define its default install configuration. A key choice -that bootc by default leaves up to the operating system image is the root filesystem -type. +To use the `to-disk` installation flow, the container should include a root filesystem +type. If it does not, then each user will need to specify `install to-disk --filesystem`. -To enable `bootc install` as part of your OS/distribution base image, +To set a default filesystem type for `bootc install to-disk` as part of your OS/distribution base image, create a file named `/usr/lib/bootc/install/00-.toml` with the contents of the form: ```toml @@ -112,8 +112,6 @@ create a file named `/usr/lib/bootc/install/00-.toml` with the contents type = "xfs" ``` -The `install.filesystem.root` value **MUST** be set. - Configuration files found in this directory will be merged, with higher alphanumeric values taking precedence. If for example you are building a derived container image from the above OS, you could create a `50-myos.toml` that sets `type = "btrfs"` which will override the @@ -223,3 +221,15 @@ a different sandboxing tool (e.g. [bubblewrap](https://github.com/containers/bub This argument is mainly useful for 3rd-party tooling for building disk images from bootable containers (e.g. based on [osbuild](https://github.com/osbuild/osbuild)). + +## Configuring machine-local state + +Per the [filesystem](filesystem.md) section, `/etc` and `/var` are machine-local +state by default. If you want to inject additional content after the installation +process, at the current time this can be done by manually finding the +target "deployment root" which will be underneath `/ostree/deploy/