docs: Describe how to boot local builds

We want to make this use case feel awesome; today it doesn't for multiple reasons. We probably want a `bootc status --booted-image` which would print the digested pull spec to start. Then one could at least `podman pull $(bootc status --booted-image)`. But we clearly *also* want to streamline exporting from the local ostree storage back into a container, which has some downsides/bugs right now. Signed-off-by: Colin Walters <[email protected]>
containers · May 6, 2024 · 0a87e76 · 0a87e76
1 parent 189adfe
commit 0a87e76
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 0 deletions.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -18,6 +18,7 @@
 
 - [Upgrade and rollback](upgrades.md)
 - [Offline/disconnected updates](offline-updates.md)
+- [Booting local builds](booting-local-builds.md)
 - [`man bootc`](man/bootc.md)
 - [`man bootc status`](man/bootc-status.md)
 - [`man bootc upgrade`](man/bootc-upgrade.md)

diff --git a/docs/src/booting-local-builds.md b/docs/src/booting-local-builds.md
@@ -0,0 +1,41 @@
+# Booting local builds
+
+In some scenarios, you may want to boot a *locally* built
+container image, in order to apply a persistent hotfix
+to a specific server, or as part of a development/testing
+scenario.
+
+## Building a new local image
+
+At the current time, the bootc host container storage is distinct
+from that of the `podman` container runtime storage (default
+configuration in `/var/lib/containers`).
+
+It not currently streamlined to export the booted host container
+storage into the podman storage.
+
+Hence today, to replicate the exact container image the
+host has booted, take the container image referenced
+in `bootc status` and turn it into a `podman pull`
+invocation.
+
+Next, craft a container build file with your desired changes:
+```
+FROM <image>
+RUN apt|dnf upgrade https://example.com/systemd-hotfix.package
+```
+
+## Copying an updated image into the bootc storage
+
+This command is straightforward; we just need to tell bootc
+to fetch updates from `containers-storage`, which is the
+local "application" container runtime (podman) storage:
+
+```
+$ bootc switch --transport containers-storage quay.io/fedora/fedora-bootc:40
+```
+
+From there, the new image will be queued for the next boot
+and a `reboot` will apply it.
+
+For more on valid transports, see [containers-transports](https://github.com/containers/image/blob/main/docs/containers-transports.5.md).