From 3ee7cef0d843fbca0df0ce3023968b96a0a7d132 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Thu, 16 May 2024 12:36:03 -0400 Subject: [PATCH] docs: Clarify mutability at build vs runtime Came up in chat; we have this elsewhere, but let's reinforce this here. Signed-off-by: Colin Walters --- docs/src/building/guidance.md | 9 +++++++++ docs/src/filesystem.md | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/docs/src/building/guidance.md b/docs/src/building/guidance.md index 2711ca27e..ace6114c9 100644 --- a/docs/src/building/guidance.md +++ b/docs/src/building/guidance.md @@ -20,6 +20,15 @@ Let's however restate a base goal of this project: Every tool and technique for creating application base images should apply to the host Linux OS as much as possible. +## Understanding mutability + +When run as a container (particularly as part of a build), bootc-compatible +images have all parts of the filesystem (e.g. `/usr` in particular) as fully +mutable state, and writing there is encouraged (see below). + +When "deployed" to a physical or virtual machine, the container image +files are read-only by default; for more, see [filesystem](../filesystem.md). + ## Installing software For package management tools like `apt`, `dnf`, `zypper` etc. diff --git a/docs/src/filesystem.md b/docs/src/filesystem.md index d456b6725..aa7af2913 100644 --- a/docs/src/filesystem.md +++ b/docs/src/filesystem.md @@ -16,6 +16,15 @@ enabled = true This will ensure that the entire `/` is a read-only filesystem. +## Understanding container build/runtime vs deployment + +When run *as a container* (e.g. as part of a container build), the +filesystem is fully mutable in order to allow derivation to work. +For more on container builds, see [build guidance](building/guidance.md). + +The rest of this document describes the state of the system when +"deployed" to a physical or virtual machine, and managed by `bootc`. + ## Understanding physical vs logical root with `/sysroot` When the system is fully booted, it is into the equivalent of a `chroot`.