Merge pull request #541 from cgwalters/clarify-mutability

docs: Clarify mutability at build vs runtime

Author: cgwalters

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.

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`.