From 0a87e765544766163c1ff5bf6a45a5871df9022a Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Mon, 6 May 2024 09:25:15 -0600
Subject: [PATCH] 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 <walters@verbum.org>
---
 docs/src/SUMMARY.md              |  1 +
 docs/src/booting-local-builds.md | 41 ++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 docs/src/booting-local-builds.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index a814f99e..624f912c 100644
--- 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
new file mode 100644
index 00000000..6edaaccd
--- /dev/null
+++ 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).