From b1d9cd6540a703819d8bf5015b1774e709bfb2d4 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Thu, 29 Feb 2024 17:09:42 -0500 Subject: [PATCH] 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!) Signed-off-by: Colin Walters --- .github/labeler.yml | 1 - .github/workflows/docs.yml | 27 ++-- docs/.gitignore | 1 + docs/Gemfile | 14 -- docs/book.toml | 6 + docs/faq.md | 17 --- docs/index.md | 134 ------------------ docs/src/SUMMARY.md | 37 +++++ docs/{ => src}/bootc-images.md | 15 +- docs/{install.md => src/bootc-install.md} | 4 - {manpages-md => docs/src}/bootc.md | 0 docs/src/filesystem.md | 65 +++++++++ docs/src/installation.md | 17 +++ docs/src/intro.md | 14 ++ .../bootc-fetch-apply-updates-service.md | 1 + .../bootc-fetch-apply-updates.service.md | 0 .../src/man-md}/bootc-install-config.md | 0 {manpages-md => docs/src/man}/bootc-edit.md | 0 .../man/bootc-fetch-apply-updates-service.md | 1 + docs/src/man/bootc-install-config.md | 1 + .../man}/bootc-install-print-configuration.md | 0 .../src/man}/bootc-install-to-disk.md | 0 .../src/man}/bootc-install-to-filesystem.md | 0 .../src/man}/bootc-install.md | 0 {manpages-md => docs/src/man}/bootc-status.md | 0 {manpages-md => docs/src/man}/bootc-switch.md | 0 .../src/man}/bootc-upgrade.md | 0 .../src/man}/bootc-usr-overlay.md | 0 docs/src/man/bootc.md | 57 ++++++++ docs/{usage.md => src/offline-updates.md} | 13 +- docs/src/related.md | 1 + docs/src/relationship-oci-artifacts.md | 5 + docs/{ => src}/relationship-particles.md | 4 - .../{relationship.md => src/relationships.md} | 8 +- docs/src/upgrades.md | 38 +++++ manpages-md/README.md | 6 - xtask/src/xtask.rs | 7 +- 37 files changed, 283 insertions(+), 211 deletions(-) create mode 100644 docs/.gitignore delete mode 100644 docs/Gemfile create mode 100644 docs/book.toml delete mode 100644 docs/faq.md delete mode 100644 docs/index.md create mode 100644 docs/src/SUMMARY.md rename docs/{ => src}/bootc-images.md (88%) rename docs/{install.md => src/bootc-install.md} (99%) rename {manpages-md => docs/src}/bootc.md (100%) create mode 100644 docs/src/filesystem.md create mode 100644 docs/src/installation.md create mode 100644 docs/src/intro.md create mode 100644 docs/src/man-md/bootc-fetch-apply-updates-service.md rename {manpages-md-extra => docs/src/man-md}/bootc-fetch-apply-updates.service.md (100%) rename {manpages-md-extra => docs/src/man-md}/bootc-install-config.md (100%) rename {manpages-md => docs/src/man}/bootc-edit.md (100%) create mode 100644 docs/src/man/bootc-fetch-apply-updates-service.md create mode 100644 docs/src/man/bootc-install-config.md rename {manpages-md => docs/src/man}/bootc-install-print-configuration.md (100%) rename {manpages-md => docs/src/man}/bootc-install-to-disk.md (100%) rename {manpages-md => docs/src/man}/bootc-install-to-filesystem.md (100%) rename {manpages-md => docs/src/man}/bootc-install.md (100%) rename {manpages-md => docs/src/man}/bootc-status.md (100%) rename {manpages-md => docs/src/man}/bootc-switch.md (100%) rename {manpages-md => docs/src/man}/bootc-upgrade.md (100%) rename {manpages-md => docs/src/man}/bootc-usr-overlay.md (100%) create mode 100644 docs/src/man/bootc.md rename docs/{usage.md => src/offline-updates.md} (65%) create mode 100644 docs/src/related.md create mode 100644 docs/src/relationship-oci-artifacts.md rename docs/{ => src}/relationship-particles.md (99%) rename docs/{relationship.md => src/relationships.md} (96%) create mode 100644 docs/src/upgrades.md delete mode 100644 manpages-md/README.md diff --git a/.github/labeler.yml b/.github/labeler.yml index 03320275..7c2c0d45 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -2,7 +2,6 @@ documentation: - changed-files: - any-glob-to-any-file: - 'docs/*' - - 'manpages-md/*' - README.md area/install: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2492534c..56dd8b85 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..7585238e --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index 1ffd2a02..00000000 --- a/docs/Gemfile +++ /dev/null @@ -1,14 +0,0 @@ -# Bundler setup for jekyll to be deployed on github pages. - -source "https://rubygems.org" - -# Note that we're using the github-pages gem to mimic the GitHub pages -# automated setup. That installs jekyll, a default set of jekyll -# plugins, and a modified jekyll configuration. -group :jekyll_plugins do - gem "github-pages" - gem "jekyll-remote-theme" -end - -# Prefer the GitHub flavored markdown version of kramdown. -gem "kramdown-parser-gfm" diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 00000000..d73a1d0e --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Colin Walters"] +language = "en" +multilingual = false +src = "src" +title = "bootc" diff --git a/docs/faq.md b/docs/faq.md deleted file mode 100644 index 0c619f6a..00000000 --- a/docs/faq.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -nav_order: 4 ---- - -# Frequently Asked Questions - -## How do users include their own packages/binaries in a custom "bootc compatible" container? - -The "bootc compatible" containers are OCI container images, so you can customize them in the same way you build containers today. This means using a Containerfile to customize your image and build tools like `buildah`, `podman build`, or `docker build` to generate your customized "bootc compatible" container image. - -For examples of how use build a "bootc compatible" base image, see the [centos-boot repo](https://github.com/CentOS/centos-boot) as a starting point. For examples of how to use a Containerfile to build a customized "bootc compatible" image, see the [centos-boot-layered repo](https://github.com/CentOS/centos-boot-layered). - -## 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. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index a5872e65..00000000 --- a/docs/index.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -nav_order: 1 ---- - -# bootc - -Transactional, in-place operating system updates using OCI/Docker container images. - -STATUS: Stable enough for dev/test by interested parties, but all interfaces are subject to change. - -# Motivation - -The original Docker container model of using "layers" to model -applications has been extremely successful. This project -aims to apply the same technique for bootable host systems - using -standard OCI/Docker containers as a transport and delivery format -for base operating system updates. - -The container image includes a Linux kernel (in e.g. `/usr/lib/modules`), -which is used to boot. At runtime on a target system, the base userspace is -*not* itself running in a container by default. For example, assuming -systemd is in use, systemd acts as pid1 as usual - there's no "outer" process. - -## ostree - -This project currently leverages significant work done in -[the ostree project](https://github.com/ostreedev/ostree-rs-ext/). - -In the future, there may be non-ostree backends. - -## Modeling operating system hosts as containers - -The bootc project suggests that Linux operating systems and distributions -to provide a new kind of "bootable" base image, distinct from "application" -base images. See below for available images. - -Effectively, these images contain a Linux kernel - and while this kernel -is not used when the image is used via e.g. `podman|docker run`, it *is* -used when booted via `bootc`. - -In the current defaults, `/etc` and `/var` both act a bit like -mounted, persistent volumes. -More on this in [the ostree docs](https://ostreedev.github.io/ostree/adapting-existing/#system-layout). - -## Status - -The core `bootc update` functionality is really just the same -technology which has shipped for some time in rpm-ostree so there -should be absolutely no worries about using it for OS updates. -A number of people do this today. - -That said bootc is in active development and some parts -are subject to change, such as the command line interface and -the CRD-like API exposed via `bootc edit`.` - -The `bootc install` functionality is also more experimental. - -## Using bootc - -### Installing - - * 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: - -* [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. - -To build base images "from scratch", see [bootc-images.md](bootc-images.md). - -### Deriving from and switching to base images - -A toplevel goal is that *every tool and technique* a Linux system -administrator knows around how to build, inspect, mirror and manage -application containers also applies to bootable host systems. - -There are a number of examples in e.g. [coreos/layering-examples](https://github.com/coreos/layering-examples). - -First, build a derived container using any container build tooling. - -#### Using `bootc install` - -The `bootc install` command has two high level sub-commands; `to-disk` and `to-filesystem`. - -The `bootc install to-disk` handles basically everything in taking the current container -and writing it to a disk, and set it up for booting and future in-place upgrades. - -In brief, the idea is that every container image shipping `bootc` also comes with a simple -installer that can set a system up to boot from it. Crucially, if you create a -*derivative* container image from a stock OS container image, it also automatically -supports `bootc install`. - -For more information, please see [install.md](install.md) as well as the [../manpages-md/bootc-install.md] manpage. - -#### Switching from an existing ostree-based system - -If you have [an operating system already using ostree](https://ostreedev.github.io/ostree/#operating-systems-and-distributions-using-ostree) then you can use `bootc switch`: - -``` -$ bootc switch quay.io/examplecorp/custom:latest -``` - -This will preserve existing state in `/etc` and `/var` - for example, -host SSH keys and home directories. There may be some issues with uid/gid -drift in this scenario however. - -### Upgrading - -Once a chosen container image is used as the boot source, further -invocations of `bootc upgrade` from the installed operating system -will fetch updates from the container image registry. - -This is backed today by ostree, implementing an A/B style upgrade system. -Changes to the base image are staged, and the running system is not -changed by default. - -Use `bootc upgrade --apply` to apply updates; today this will always -reboot. - -# More links - -- [rpm-ostree container](https://coreos.github.io/rpm-ostree/container/) -- [centos-boot](https://github.com/centos/centos-boot) -- [coreos/layering-examples](https://github.com/coreos/layering-examples) - diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 00000000..cf2b5e98 --- /dev/null +++ b/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) diff --git a/docs/bootc-images.md b/docs/src/bootc-images.md similarity index 88% rename from docs/bootc-images.md rename to docs/src/bootc-images.md index afa1470c..3c736354 100644 --- a/docs/bootc-images.md +++ b/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. diff --git a/docs/install.md b/docs/src/bootc-install.md similarity index 99% rename from docs/install.md rename to docs/src/bootc-install.md index b15cc64d..00af7a6b 100644 --- a/docs/install.md +++ b/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 diff --git a/manpages-md/bootc.md b/docs/src/bootc.md similarity index 100% rename from manpages-md/bootc.md rename to docs/src/bootc.md diff --git a/docs/src/filesystem.md b/docs/src/filesystem.md new file mode 100644 index 00000000..ed9b4f7e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 00000000..708e1c67 --- /dev/null +++ b/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. diff --git a/docs/src/intro.md b/docs/src/intro.md new file mode 100644 index 00000000..6e158dd4 --- /dev/null +++ b/docs/src/intro.md @@ -0,0 +1,14 @@ +# bootc + +Transactional, in-place operating system updates using OCI/Docker container images. + +The original Docker container model of using "layers" to model +applications has been extremely successful. This project +aims to apply the same technique for bootable host systems - using +standard OCI/Docker containers as a transport and delivery format +for base operating system updates. + +The container image includes a Linux kernel (in e.g. `/usr/lib/modules`), +which is used to boot. At runtime on a target system, the base userspace is +*not* itself running in a container by default. For example, assuming +systemd is in use, systemd acts as pid1 as usual - there's no "outer" process. diff --git a/docs/src/man-md/bootc-fetch-apply-updates-service.md b/docs/src/man-md/bootc-fetch-apply-updates-service.md new file mode 100644 index 00000000..ec1dd931 --- /dev/null +++ b/docs/src/man-md/bootc-fetch-apply-updates-service.md @@ -0,0 +1 @@ +# man bootc-fetch-apply-updates.service diff --git a/manpages-md-extra/bootc-fetch-apply-updates.service.md b/docs/src/man-md/bootc-fetch-apply-updates.service.md similarity index 100% rename from manpages-md-extra/bootc-fetch-apply-updates.service.md rename to docs/src/man-md/bootc-fetch-apply-updates.service.md diff --git a/manpages-md-extra/bootc-install-config.md b/docs/src/man-md/bootc-install-config.md similarity index 100% rename from manpages-md-extra/bootc-install-config.md rename to docs/src/man-md/bootc-install-config.md diff --git a/manpages-md/bootc-edit.md b/docs/src/man/bootc-edit.md similarity index 100% rename from manpages-md/bootc-edit.md rename to docs/src/man/bootc-edit.md diff --git a/docs/src/man/bootc-fetch-apply-updates-service.md b/docs/src/man/bootc-fetch-apply-updates-service.md new file mode 100644 index 00000000..ec1dd931 --- /dev/null +++ b/docs/src/man/bootc-fetch-apply-updates-service.md @@ -0,0 +1 @@ +# man bootc-fetch-apply-updates.service diff --git a/docs/src/man/bootc-install-config.md b/docs/src/man/bootc-install-config.md new file mode 100644 index 00000000..82321666 --- /dev/null +++ b/docs/src/man/bootc-install-config.md @@ -0,0 +1 @@ +# man bootc-install-config diff --git a/manpages-md/bootc-install-print-configuration.md b/docs/src/man/bootc-install-print-configuration.md similarity index 100% rename from manpages-md/bootc-install-print-configuration.md rename to docs/src/man/bootc-install-print-configuration.md diff --git a/manpages-md/bootc-install-to-disk.md b/docs/src/man/bootc-install-to-disk.md similarity index 100% rename from manpages-md/bootc-install-to-disk.md rename to docs/src/man/bootc-install-to-disk.md diff --git a/manpages-md/bootc-install-to-filesystem.md b/docs/src/man/bootc-install-to-filesystem.md similarity index 100% rename from manpages-md/bootc-install-to-filesystem.md rename to docs/src/man/bootc-install-to-filesystem.md diff --git a/manpages-md/bootc-install.md b/docs/src/man/bootc-install.md similarity index 100% rename from manpages-md/bootc-install.md rename to docs/src/man/bootc-install.md diff --git a/manpages-md/bootc-status.md b/docs/src/man/bootc-status.md similarity index 100% rename from manpages-md/bootc-status.md rename to docs/src/man/bootc-status.md diff --git a/manpages-md/bootc-switch.md b/docs/src/man/bootc-switch.md similarity index 100% rename from manpages-md/bootc-switch.md rename to docs/src/man/bootc-switch.md diff --git a/manpages-md/bootc-upgrade.md b/docs/src/man/bootc-upgrade.md similarity index 100% rename from manpages-md/bootc-upgrade.md rename to docs/src/man/bootc-upgrade.md diff --git a/manpages-md/bootc-usr-overlay.md b/docs/src/man/bootc-usr-overlay.md similarity index 100% rename from manpages-md/bootc-usr-overlay.md rename to docs/src/man/bootc-usr-overlay.md diff --git a/docs/src/man/bootc.md b/docs/src/man/bootc.md new file mode 100644 index 00000000..d8c313ea --- /dev/null +++ b/docs/src/man/bootc.md @@ -0,0 +1,57 @@ +# NAME + +bootc - Deploy and transactionally in-place with bootable container +images + +# SYNOPSIS + +**bootc** \[**-h**\|**\--help**\] \<*subcommands*\> + +# DESCRIPTION + +Deploy and transactionally in-place with bootable container images. + +The \`bootc\` project currently uses ostree-containers as a backend to +support a model of bootable container images. Once installed, whether +directly via \`bootc install\` (executed as part of a container) or via +another mechanism such as an OS installer tool, further updates can be +pulled via e.g. \`bootc upgrade\`. + +Changes in \`/etc\` and \`/var\` persist. + +# OPTIONS + +**-h**, **\--help** + +: Print help (see a summary with -h) + +# SUBCOMMANDS + +bootc-upgrade(8) + +: Download and queue an updated container image to apply + +bootc-switch(8) + +: Target a new container image reference to boot + +bootc-edit(8) + +: Apply full changes to the host specification + +bootc-status(8) + +: Display status + +bootc-usr-overlay(8) + +: Add a transient writable overlayfs on \`/usr\` that will be + discarded on reboot + +bootc-install(8) + +: Install the running container to a target + +bootc-help(8) + +: Print this message or the help of the given subcommand(s) diff --git a/docs/usage.md b/docs/src/offline-updates.md similarity index 65% rename from docs/usage.md rename to docs/src/offline-updates.md index 0ec7e736..2bfe2037 100644 --- a/docs/usage.md +++ b/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 diff --git a/docs/src/related.md b/docs/src/related.md new file mode 100644 index 00000000..99cb2a19 --- /dev/null +++ b/docs/src/related.md @@ -0,0 +1 @@ +# Related projects diff --git a/docs/src/relationship-oci-artifacts.md b/docs/src/relationship-oci-artifacts.md new file mode 100644 index 00000000..5c1ec7f5 --- /dev/null +++ b/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. diff --git a/docs/relationship-particles.md b/docs/src/relationship-particles.md similarity index 99% rename from docs/relationship-particles.md rename to docs/src/relationship-particles.md index f295f4d0..dd6893b7 100644 --- a/docs/relationship-particles.md +++ b/docs/src/relationship-particles.md @@ -1,7 +1,3 @@ ---- -nav_order: 6 ---- - # Relationship with systemd "particles" There is an excellent [vision blog entry](https://0pointer.net/blog/fitting-everything-together.html) diff --git a/docs/relationship.md b/docs/src/relationships.md similarity index 96% rename from docs/relationship.md rename to docs/src/relationships.md index fe598cb7..75e724c2 100644 --- a/docs/relationship.md +++ b/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. diff --git a/docs/src/upgrades.md b/docs/src/upgrades.md new file mode 100644 index 00000000..2dc0bd0b --- /dev/null +++ b/docs/src/upgrades.md @@ -0,0 +1,38 @@ +# Managing upgrades + +Right now, bootc is a quite simple tool that is designed to do just +a few things well. One of those is transactionally fetching new operating system +updates from a registry and booting into them, while supporting rollback. + +## The `bootc upgrade` verb + +This will query the registry and queue an updated container image for the next boot. + +This is backed today by ostree, implementing an A/B style upgrade system. +Changes to the base image are staged, and the running system is not +changed by default. + +Use `bootc upgrade --apply` to auto-apply if there are queued changes. + +There is also an opinionated `bootc-fetch-apply-updates.timer` and corresponding +service available in upstream for operating systems and distributions +to enable. + +## Changing the container image source + +Another useful pattern to implement can be to use a management agent +to invoke `bootc switch` to implement e.g. blue/green deployments, +where some hosts are rolled onto a new image independently of others. + +```shell +bootc switch quay.io/examplecorp/os-prod-blue:lastest +``` + +This will preserve existing state in `/etc` and `/var` - for example, +host SSH keys and home directories. + +## Rollback + +At the current time, bootc does not ship with an opinionated integrated +rollback flow. However, bootc always maintains (by default) a +`rollback` container image that is accessible via `bootc status`. diff --git a/manpages-md/README.md b/manpages-md/README.md deleted file mode 100644 index 17efe1ea..00000000 --- a/manpages-md/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Auto-generated manpages - -These markdown files are automatically generated via -`cargo xtask man2markdown`. - -Start with [bootc.md](bootc.md). diff --git a/xtask/src/xtask.rs b/xtask/src/xtask.rs index a58fa0d8..0496b11d 100644 --- a/xtask/src/xtask.rs +++ b/xtask/src/xtask.rs @@ -76,7 +76,7 @@ fn manpages(sh: &Shell) -> Result<()> { .run()?; // We also have some man pages for the systemd units which are canonically // maintained as markdown; convert them to man pages. - let extradir = sh.current_dir().join("manpages-md-extra"); + let extradir = sh.current_dir().join("docs/src/man-md"); for ent in std::fs::read_dir(extradir)? { let ent = ent?; let srcpath = ent.path(); @@ -103,7 +103,8 @@ fn manpages(sh: &Shell) -> Result<()> { } /// Generate markdown files (converted from the man pages, which are generated -/// from the Rust sources) into docs/man. This process is currently manual. +/// from the Rust sources) into docs/src, which ends up in the rendered +/// documentation. This process is currently manual. #[context("man2markdown")] fn man2markdown(sh: &Shell) -> Result<()> { manpages(sh)?; @@ -117,7 +118,7 @@ fn man2markdown(sh: &Shell) -> Result<()> { .file_stem() .and_then(|name| name.to_str()) .ok_or_else(|| anyhow!("Expected filename in {path:?}"))?; - let target = format!("manpages-md/{filename}.md"); + let target = format!("docs/src/{filename}.md"); cmd!( sh, "pandoc --from=man --to=markdown --output={target} {path}"