keremet/rpm-ostree
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Misc doc tweaks/cleanups

Browse Source 
- Link to osbuild blog
- Drop CentOS 7 stuff
- clarify goals a bit
This commit is contained in:
Colin Walters 2021-02-12 20:33:25 +00:00 committed by OpenShift Merge Robot
parent 35342dabca
commit 04839e200f
2 changed files with 50 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
docs/compose-server.md
View File

@ -17,7 +17,13 @@ OSTree commits *also* want to generate bootable disk images, and rpm-ostree
has nothing to do with that. has nothing to do with that.
One example higher level tool that takes care of both OSTree commit generation One example higher level tool that takes care of both OSTree commit generation
and bootable disk images is [coreos-assembler](https://github.com/coreos/coreos-assembler). and bootable disk images is [coreos-assembler](https://github.com/coreos/coreos-assembler);
it is strongly oriented towards "CoreOS-like" systems which include rpm-ostree
and Ignition.
The [osbuild](https://www.osbuild.org/) project has some support for
rpm-ostree based systems. See [this blog entry](https://www.osbuild.org/news/2020-06-01-how-to-ostree-anaconda.html)
for example.
## Background on managing an OSTree repository ## Background on managing an OSTree repository
@ -27,60 +33,39 @@ of the OSTree manual:
- [buildsystem-and-repos](https://ostreedev.github.io/ostree/buildsystem-and-repos/) - [buildsystem-and-repos](https://ostreedev.github.io/ostree/buildsystem-and-repos/)
- [repository-management](https://ostreedev.github.io/ostree/repository-management/) - [repository-management](https://ostreedev.github.io/ostree/repository-management/)
## Generating OSTree commits from a CentOS base ## Generating OSTree commits in a container
First, you'll need a copy of `rpm-ostree`. The current recommendation is to use `rpm-ostree compose tree` runs well in an unprivileged (or "run as root")
a privileged container, but you can also install `rpm-ostree` directly to a podman container. You can also use other container tools, they are just less
physical or virtual machine. frequently tested.
It's included in the package collection for Fedora, and there You can also directly install `rpm-ostree` on a traditional `yum/rpm` based
are [CentOS Core packages](http://buildlogs.centos.org/centos/7/atomic/x86_64/Packages/) as virtual (or physical) machine - it won't affect your host. However, containers
well as [bleeding edge CentOS builds](https://ci.centos.org/job/atomic-rdgo-centos7/). are encouraged.
You can create a privileged container with e.g. `podman` via: `podman run ## Choosing a base config
--privileged registry.fedoraproject.org/fedora:27 ...`. However you create the
environment, run `yum -y install rpm-ostree`.
A good first thing to try would be using Currently, rpm-ostree is fairly coupled to the Fedora project. We are open to supporting
the other distributions however.
[CentOS Atomic Host](https://github.com/CentOS/sig-atomic-buildscripts/tree/downstream) metadata
to generate a custom host.
One time setup, where we clone the git repository, then make two OSTree repos, Example base rpm-ostree "manifest repositories" are:
one for doing builds, one for export via HTTP:
``` - [Silverblue](https://pagure.io/workstation-ostree-config)
# mkdir /srv/centos-atomic - [IoT](https://pagure.io/fedora-iot/ostree)
# cd /srv/centos-atomic - [Fedora CoreOS](https://github.com/coreos/fedora-coreos-config/)
# git clone https://github.com/CentOS/sig-atomic-buildscripts -b downstream
# mkdir build-repo
# ostree --repo=build-repo init --mode=bare-user
# mkdir repo
# ostree --repo=repo init --mode=archive
```
We'll also want to cache downloaded RPMs:
```
# mkdir cache
```
## Running `rpm-ostree compose tree` ## Running `rpm-ostree compose tree`
This program takes as input a manifest file that describes the target system, This program takes as input a manifest file that describes the target system,
and commits the result to an OSTree repository. and commits the result to an OSTree repository.
The input format is a JSON "treefile". See examples in The input format is a YAML (or JSON) "treefile".
`api-doc/treefile-examples`. More real-world examples include the manifest
for
[Fedora Atomic](https://pagure.io/fedora-atomic/blob/master/f/fedora-atomic-host.json) and
[CentOS Atomic](https://github.com/CentOS/sig-atomic-buildscripts/blob/downstream/centos-atomic-host.json).
If you're doing this multiple times, it's strongly recommended to create a cache If you're doing this multiple times, it's strongly recommended to create a cache
directory: directory:
``` ```
# rpm-ostree compose tree --unified-core --cachedir=cache --repo=/srv/centos-atomic/build-repo sig-atomic-buildscripts/centos-atomic-host.json # rpm-ostree compose tree --unified-core --cachedir=cache --repo=/srv/repo /path/to/manifest.yaml
``` ```
This will download RPMs from the referenced repos, and commit the result to the This will download RPMs from the referenced repos, and commit the result to the
@ -89,7 +74,7 @@ OSTree repository, using the ref named by `ref`.
Once we have that commit, let's export it: Once we have that commit, let's export it:
``` ```
# ostree --repo=repo pull-local build-repo centos-atomic-host/7/x86_64/standard # ostree --repo=repo pull-local build-repo exampleos/8/x86_64/stable
``` ```
You can tell client systems to rebase to it by combining `ostree remote add`, You can tell client systems to rebase to it by combining `ostree remote add`,
@ -97,8 +82,6 @@ and `rpm-ostree rebase` on the client side.
## More information ## More information
* [run-treecompose script from FAHC](https://pagure.io/fedora-atomic-host-continuous/blob/2f1214c9ff35e55ec111db86be96e14d4b6040d6/f/centos-ci/run-treecompose) - https://www.osbuild.org/news/2020-06-01-how-to-ostree-anaconda.html
* [Build Your Own Atomic](https://github.com/jasonbrooks/byo-atomic) - https://github.com/coreos/coreos-assembler
* [Build Your Own Atomic Image, Updated](http://www.projectatomic.io/blog/2014/08/build-your-own-atomic-centos-or-fedora/)
* [Creating custom Atomic trees, images, and installers, part 1](http://developerblog.redhat.com/2015/01/08/creating-custom-atomic-trees-images-and-installers-part-1/)
* [Creating custom Atomic trees, images, and installers, part 2](http://developerblog.redhat.com/2015/01/15/creating-custom-atomic-trees-images-and-installers-part-2/)

38
docs/index.md
View File

@ -40,9 +40,9 @@ many of the benefits of both together.
**Features:** **Features:**
- Transactional, background image-based (versioned/checksummed) upgrades - Transactional, background image-based (versioned/checksummed) upgrades
- OS rollback without affecting user data (`/usr` but not `/etc`, `/var`) via libostree - OS rollback without affecting user data (`/usr`, `/etc` but not `/var`) via libostree
- Client-side package layering (and overrides) - Client-side package layering (and overrides)
- Easily make your own: `rpm-ostree compose tree` and [CoreOS Assembler](https://github.com/coreos/coreos-assembler) - Easily make your own derivatives
## Projects using rpm-ostree ## Projects using rpm-ostree
@ -61,16 +61,26 @@ Originally, it was productized as part of [Project Atomic](http://www.projectato
## Getting started ## Getting started
If you want to try the system as a user, we recommend If you want to try the system as a user, see the main [Fedora website](https://getfedora.org/)
[Fedora CoreOS](https://getfedora.org/en/coreos). If you are interested in which has several versions that use rpm-ostree, including Silverblue, IoT and CoreOS.
assembling your own systems, see [compose server](compose-server.md). If you are interested in assembling your own systems, see [compose server](compose-server.md).
## Why? ## Why?
Package systems such as apt and yum are highly prevalent in Linux-based Package systems such as apt and yum are highly prevalent in Linux-based
operating systems. The core premise of rpm-ostree is that image-based updates operating systems. They offer a lot of flexiblity, but have many failure
modes.
The core premise of rpm-ostree is that offline transactional image-based updates
should be the default. This provides a high degree of predictability and should be the default. This provides a high degree of predictability and
resiliency. However, where rpm-ostree is fairly unique in the ecosystem is resiliency. The operating system vendor can focus a lot of effort
on testing the "base images" as a unit.
Further, image based updates simply work better at scale. For "IoT" style devices
it's very inefficient to have each machine perform dependency resolution,
run package scripts etc. And the same is true for many server datacenter
use cases.
Where rpm-ostree is fairly unique in the ecosystem is
supporting client-side package layering and overrides; deeply integrating RPM supporting client-side package layering and overrides; deeply integrating RPM
as an (optional) layer on top of OSTree. as an (optional) layer on top of OSTree.
@ -89,6 +99,10 @@ installing and updating client-side packages constructs a new filesystem root,
it does not by default affect your booted root. This preserves the "image" it does not by default affect your booted root. This preserves the "image"
nature of the system. nature of the system.
By its nature as a hybrid image/package system, rpm-ostree is intended
to span nearly all use cases of current package systems *and* image
systems.
## Why would I want to use it? ## Why would I want to use it?
One major feature rpm-ostree has over traditional package management One major feature rpm-ostree has over traditional package management
@ -98,14 +112,6 @@ is atomic upgrade/rollback. It supports a model where an OS vendor
images", and client systems can replicate those, and possibly layer on images", and client systems can replicate those, and possibly layer on
additional packages. additional packages.
rpm-ostree is a core part of the [Project Atomic](http://www.projectatomic.io/)
effort, which uses rpm-ostree to provide a minimal host for
Docker formatted Linux containers.
We expect most users will be interested in rpm-ostree on the client
side, using it to replicate a base system, and possibly layer on
additional packages, and use containers for applications.
## Why not implement these changes in an existing package manager? ## Why not implement these changes in an existing package manager?
The [OSTree related projects](https://coreos.github.io/ostree/related-projects/) The [OSTree related projects](https://coreos.github.io/ostree/related-projects/)