docs: Various elaborations

- Clarify c/storage instance and LBIs in multiple places - Flesh out/clarify some differences between bootc and rpm-ostree Signed-off-by: Colin Walters <[email protected]>
cgwalters · Oct 19, 2024 · 9c51ed4 · 9c51ed4
1 parent d459001
commit 9c51ed4
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 10 deletions.
diff --git a/docs/src/filesystem-storage.md b/docs/src/filesystem-storage.md
@@ -2,14 +2,17 @@
 
 The bootc project uses [ostree](https://github.com/ostreedev/ostree/) and specifically
 the [ostree-rs-ext](https://github.com/ostreedev/ostree-rs-ext/) Rust library
-which handles storage of container images on top of an ostree-based system.
+which handles storage of container images on top of an ostree-based system for
+the booted host, and additionally there is a
+[containers/storage](https://github.com/containers/storage) instance for [logically bound images](logically-bound-images.md).
 
 ## Architecture
 
 ```mermaid
 flowchart TD
     bootc --- ostree-rs-ext --- ostree-rs --- ostree
     ostree-rs-ext --- containers-image-proxy-rs --- skopeo --- containers/image
+    bootc --- podman --- image-storage["containers/{image,storage}"]
 ```
 
 There were two high level goals that drove the design of the current system
@@ -88,3 +91,7 @@ from an OCI image or some other mechanism; it just targets a
 prepared flattened filesystem tree.
 
 This is what is referenced by the `ostree=` kernel commandline.
+
+## Logically bound images
+
+In addition to the base image, bootc supports [logically bound images](logically-bound-images.md).
diff --git a/docs/src/filesystem.md b/docs/src/filesystem.md
@@ -1,9 +1,11 @@
 # Filesystem
 
-As noted in other chapters, the bootc project inherits
-a lot of code from the [ostree project](https://github.com/ostreedev/ostree/).
+As noted in other chapters, the bootc project currently
+depends on [ostree project](https://github.com/ostreedev/ostree/)
+for storing the base container image. Additionally there is a [containers/storage](https://github.com/containers/storage) instance for [logically bound images](logically-bound-images.md).
 
-However, bootc is intending to be a "fresh, new container-native interface".
+However, bootc is intending to be a "fresh, new container-native interface",
+and ostree is an implementation detail.
 
 First, it is strongly recommended that bootc consumers use the ostree
 [composefs backend](https://ostreedev.github.io/ostree/composefs/); to do this,
@@ -14,7 +16,8 @@ ensure that you have a `/usr/lib/ostree/prepare-root.conf` that contains at leas
 enabled = true
 ```
 
-This will ensure that the entire `/` is a read-only filesystem.
+This will ensure that the entire `/` is a read-only filesystem which
+is very important for achieving correct semantics.
 
 ## Understanding container build/runtime vs deployment
 

diff --git a/docs/src/relationships.md b/docs/src/relationships.md
@@ -46,11 +46,18 @@ as a backing model.  Hence, when using a container source,
 `rpm-ostree upgrade` and `bootc upgrade` are effectively equivalent;
 you can use either command.
 
-However with rpm-ostree (or, perhaps re-framed as
-"dnf image"), it will continue to work to e.g. `dnf install`
-(i.e. `rpm-ostree install`) on the *client side* system.
-In addition there are other client-side mutation commands such as
-`rpm-ostree initramfs --enable`.
+### Differences from rpm-ostree
+
+- The ostree project never tried to have an opinionated "install" mechanism,
+  but bootc does with `bootc install to-filesystem`
+- Bootc has additional features such as `/usr/lib/bootc/kargs.d` and
+  [logically bound images](logically-bound-images.md).
+
+### Client side changes
+
+Currently all functionality for client-side changes
+such as `rpm-ostree install` or `rpm-ostree initramfs --enable`
+continue to work, because of the shared base.
 
 However, as soon as you mutate the system in this way, `bootc upgrade`
 will error out as it will not understand how to upgrade