wip

docs/src/SUMMARY.md

@@ -9,6 +9,7 @@
 # Using bootc
 
 - [Upgrade and rollback](upgrades.md)
+- [Offline/disconnected updates](offline-updates.md)
 - [`man bootc`](man/bootc.md)
 - [`man bootc status`](man/bootc-status.md)
 - [`man bootc upgrade`](man/bootc-upgrade.md)
@@ -32,4 +33,5 @@
 # More information
 
 - [Relationship with other projects](relationships.md)
+- [Relationship with OCI artifacs](relationship-oci-artifacts.md)
 - [Relationship with systemd "particles"](relationship-particles.md)

docs/src/bootc-images.md

@@ -11,7 +11,7 @@ or
 
 ```Dockerfile
 FROM debian
-RUN apt install kernel
+RUN apt install linux
 ```
 
 And get an image compatible with bootc.  Supporting any base image
@@ -72,9 +72,8 @@ You can then use `podman build`, `buildah`, `docker build`, or any other contain
 build tool to produce your customized image. The only requirement is that the
 container build tool supports producing OCI container images.
 
-## Using the `ostree container commit` command
+## The `ostree container commit` command
+
+You may find some references to this; it is no longer very useful
+and is not recommended.
 
-As an opt-in optimization today, you can also add `ostree container commit`
-as part of your `RUN` invocations. This will perform early detection
-of some incompatibilities but is not a strict requirement today and will not be
-in the future.

docs/src/filesystem.md

@@ -1 +1,65 @@
 # Filesystem
+
+As noted in other chapters, the bootc project inherits
+a lot of code from the [ostree project](https://github.com/ostreedev/ostree/).
+
+However, bootc is intending to be a "fresh, new container-native interface".
+
+First, it is strongly recommended that bootc consumers use the ostree
+[composefs backend](https://ostreedev.github.io/ostree/composefs/); to do this,
+ensure that you have a `/usr/lib/ostree/prepare-root.conf` that contains at least
+
+```ini
+[composefs]
+enabled = true
+```
+
+This will ensure that the entire `/` is a read-only filesystem.
+
+## `/usr`
+
+The overall recommendation is to keep all operating system content in `/usr`.  See [UsrMove](https://fedoraproject.org/wiki/Features/UsrMove) for example.
+
+## `/etc`
+
+The `/etc` directory contains persistent state by default; however,
+it is suppported to enable the [`etc.transient` config option](https://ostreedev.github.io/ostree/man/ostree-prepare-root.html).
+
+When in persistent mode, it inherits the OSTree semantics of [performing a 3-way merge](https://ostreedev.github.io/ostree/atomic-upgrades/#assembling-a-new-deployment-directory)
+across upgrades.
+
+## `/var`
+
+Content in `/var` persists by default; it is however supported to make it or subdirectories
+mount points (whether network or `tmpfs`)
+
+As of OSTree v2024.3, by default [content in /var acts like a Docker VOLUME /var](https://github.com/ostreedev/ostree/pull/3166/commits/f81b9fa1666c62a024d5ca0bbe876321f72529c7).
+
+This means that the content from the container image is copied at *initial installation time*, and not updated thereafter.
+
+## Other directories
+
+It is not supported to ship content in `/run` or `/proc` or other [API Filesystems](https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems/) in container images.
+
+Besides those, for other toplevel directories such as `/usr` `/opt`, they will be lifecycled with the container image.
+
+### `/opt`
+
+In the default suggested model of using composefs (per above) the `/opt` directory will be read-only, alongside
+other toplevels such as `/usr`.
+
+Some software expects to be able to write to its own directory in `/opt/exampleapp`.  For these
+cases, there are several options (containerizing the app, running it in a system unit that sets up custom mounts, etc.)
+
+#### Enabling transient root
+
+However, some use cases may find it easier to enable a fully transient writable rootfs by default.
+To do this, set the
+
+```
+[root]
+transient = true
+```
+
+option in `prepare-root.conf`.  In particular this will allow software to write (transiently) to `/opt`,
+with symlinks to `/var` for content that should persist.

docs/usage.md → docs/src/offline-updates.md

@@ -1,8 +1,13 @@
----
-nav_order: 3
----
+# Mirrored/disconnected upgrades
 
-# Managing bootc systems
+It is common (a best practice even) to maintain systems which default
+to being disconnected from the public Internet.
+
+## Pulling updates from a local mirror
+
+The bootc project reuses the same container libraries that are in use by `podman`;
+this means that configuring [containers-registries.conf](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)
+allows `bootc upgrade` to fetch from local mirror registries.
 
 ## Performing offline updates via USB
 

docs/src/relationship-oci-artifacts.md

@@ -0,0 +1,5 @@
+# How does the use of OCI artifacts intersect with this effort?
+
+The "bootc compatible" images are OCI container images; they do not rely on the [OCI artifact specification](https://github.com/opencontainers/image-spec/blob/main/artifacts-guidance.md) or [OCI referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#enabling-the-referrers-api).
+
+It is foreseeable that users will need to produce "traditional" disk images (i.e. raw disk images, qcow2 disk images, Amazon AMIs, etc.) from the "bootc compatible" container images using additional tools. Therefore, it is reasonable that some users may want to encapsulate those disk images as an OCI artifact for storage and distribution. However, it is not a goal to use `bootc` to produce these "traditional" disk images nor to facilitate the encapsulation of those disk images as OCI artifacts.

docs/src/relationships.md

@@ -1,7 +1,3 @@
----
-nav_order: 5
----
-
 # Relationship with other projects
 
 ## Relationship with podman
@@ -28,6 +24,10 @@ In other words, if you configure `podman` to pull images from your local mirror
 
 The simple way to say it is: A goal of `bootc` is to be the bootable-container analogue for `podman`, which runs application containers.  Everywhere one might run `podman`, one could also consider using `bootc`. 
 
+## Relationship with Image Builder (osbuild)
+
+There is a new [bootc-image-builder](https://github.com/osbuild/bootc-image-builder) project that is dedicated to the intersection of these two!
+
 ## Relationship with Kubernetes
 
 Just as `podman` does not depend on a Kubernetes API server, `bootc` will also not depend on one.