forked from containers/bootc
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- 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 <[email protected]>
- Loading branch information
Showing
37 changed files
with
283 additions
and
211 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
book |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
[book] | ||
authors = ["Colin Walters"] | ||
language = "en" | ||
multilingual = false | ||
src = "src" | ||
title = "bootc" |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Oops, something went wrong.