docs: Switch to mdbook, rework

- I don't want my life to involve ruby, and in particular `mdbook serve`
  Just Works out of the box with a single binary
- Reorganize the sections
- Some content cleanup and fixes
- Integrate the man pages into the docs (hooray!)

.github/labeler.yml

@@ -2,7 +2,6 @@ documentation:
 - changed-files:
   - any-glob-to-any-file:
     - 'docs/*'
-    - 'manpages-md/*'
     - README.md
 
 area/install:

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Docs
+name: Deploy docs to pages
 
 on:
   push:
@@ -12,25 +12,32 @@ permissions:
 
 concurrency:
   group: "pages"
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.4.37
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+      - name: Install mdBook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
       - name: Setup Pages
+        id: pages
         uses: actions/configure-pages@v4
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: ./docs
-          destination: ./_site
+      - name: Build with mdBook
+        run: cd docs && mdbook build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/book
 
-  # Deployment job
   deploy:
     environment:
       name: github-pages

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Colin Walters"]
+language = "en"
+multilingual = false
+src = "src"
+title = "bootc"

docs/src/SUMMARY.md

@@ -0,0 +1,37 @@
+# Summary
+
+- [Introduction](intro.md)
+
+# Installation
+
+- [Installation](installation.md)
+
+# 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)
+- [`man bootc switch`](man/bootc-switch.md)
+- [`man bootc usroverlay`](man/bootc-usr-overlay.md)
+- [`man bootc-fetch-apply-updates.service`](man-md/bootc-fetch-apply-updates-service.md)
+
+# Using `bootc install`
+
+- [Understanding `bootc install`](bootc-install.md)
+- [`man bootc-install.md`](man/bootc-install.md)
+- [`man bootc-install-config`](man-md/bootc-install-config.md)
+- [`man bootc-install-to-disk.md`](man/bootc-install-to-disk.md)
+- [`man bootc-install-to-filesystem.md`](man/bootc-install-to-filesystem.md)
+
+# Architecture
+
+- [Image layout](bootc-images.md)
+- [Filesystem](filesystem.md)
+
+# More information
+
+- [Relationship with other projects](relationships.md)
+- [Relationship with OCI artifacs](relationship-oci-artifacts.md)
+- [Relationship with systemd "particles"](relationship-particles.md)

docs/bootc-images.md → docs/src/bootc-images.md

@@ -1,7 +1,3 @@
----
-nav_order: 2
----
-
 # "bootc compatible" images
 
 At the current time, it does not work to just do:
@@ -15,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
@@ -76,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/install.md → docs/src/bootc-install.md

@@ -1,7 +1,3 @@
----
-nav_order: 2
----
-
 # Installing "bootc compatible" images
 
 A key goal of the bootc project is to think of bootable operating systems

docs/src/filesystem.md

@@ -0,0 +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/src/installation.md

@@ -0,0 +1,17 @@
+# Installing the binary
+
+* Fedora: [bootc is packaged](https://bodhi.fedoraproject.org/updates/?packages=bootc).
+* CentOS Stream 9: There is a [COPR](https://copr.fedorainfracloud.org/coprs/rhcontainerbot/bootc/) tracking git main with binary packages.
+
+You can also build this project like any other Rust project, e.g. `cargo build --release` from a git clone.
+
+# Base images
+
+Many users will be more interested in base (container) images.
+
+For pre-built base images:
+
+* Any Fedora derivative already using `ostree` can be seamlessly converted into using bootc; for example, [Fedora CoreOS](https://quay.io/repository/fedora/fedora-coreos) can be used as a base image; you will want to also `rpm-ostree install bootc` in your image builds currently.
+* There is also an in-development [centos-boot](https://github.com/centos/centos-boot) project.
+
+However, bootc itself is not tied to Fedora derivatives; [this issue](https://github.com/coreos/bootupd/issues/468) tracks the main blocker for other distributions.