From 64c6f8d90603a23b344d86422e7f45b1b8de27c9 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Fri, 1 Jul 2016 22:02:06 -0400 Subject: [PATCH] docs: Separate README.md and docs index, elaborate more Have the index page be rationale/comparison for now. Closes: #370 Approved by: jlebon --- README.md | 35 +++++--------------- docs/index.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 100 insertions(+), 27 deletions(-) mode change 120000 => 100644 docs/index.md diff --git a/README.md b/README.md index 7ee19392..af79f5e2 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,26 @@ # rpm-ostree Overview -New! See the docs online at [Read The Docs (rpm-ostree)](https://rpm-ostree.readthedocs.org/en/latest/ ) - ------ - rpm-ostree is a hybrid image/package system. It uses -[OSTree](https://ostree.readthedocs.io/en/latest/) as an image format, -and uses RPM as a component model. +[OSTree](https://ostree.readthedocs.io/en/latest/) as a base image +format, and supports RPM on both the client and server side using +[libhif](https://github.com/rpm-software-management/libhif). -The project aims to bring together a hybrid of image-like upgrade -features (reliable replication, atomicity), with package-like -flexibility (introspecting trees to find package sets, package -layering, partial live updates). +For more information, see the online manual: [Read The Docs (rpm-ostree)](https://rpm-ostree.readthedocs.org/en/latest/) **Features:** - Atomic upgrades and rollback for host system updates - A server side tool to consume RPMs and commit them to an OSTree repository - - A system daemon to consume ostree commits as updates + - A system daemon to consume OSTree commits as updates Projects using rpm-ostree -------------------------- +-------------------------- [Project Atomic](http://www.projectatomic.io/) uses rpm-ostree to provide a minimal host for Docker formatted Linux containers. Replicating a base immutable OS, then using Docker for applications. -Using rpm-ostree to build OS images/trees ------------------------------------------ - -See [Compose Server](docs/manual/compose-server.md). - -Hacking -------- - -See [Hacking](HACKING.md). - -Contributing ------------- - -See [Contributing](CONTRIBUTING.md). +Manual +------ +For more information, see the online manual: [Read The Docs (rpm-ostree)](https://rpm-ostree.readthedocs.org/en/latest/) diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..5123700a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,91 @@ +# What is rpm-ostree? + +rpm-ostree is a hybrid image/package system. It uses +[OSTree](https://ostree.readthedocs.io/en/latest/) as a base image +format, and accepts RPM on both the client and server side, sharing +code with the [dnf](https://en.wikipedia.org/wiki/DNF_(software)) project; +specifically [libhif](https://github.com/rpm-software-management/libhif). + +# Getting started + +If you want to try the system as a user, we recommend +[Project Atomic](http://www.projectatomic.io/). If you are +interested in assembling your own systems, see +[compose server](manual/compose-server.md). + +# Why would I want to use it? + +One major feature rpm-ostree has over traditional package management +is atomic upgrade/rollback. It supports a model where an OS vendor +(such as [CentOS](https://www.centos.org/) or +[Fedora](https://getfedora.org/) can provide pre-assembled "base OS +images", and client systems can replicate those, and possibly layer on +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? + +The [OSTree related projects](https://ostree.readthedocs.io/en/latest/manual/related-projects/) +section covers this to a degree. As soon as one starts taking +"snapshots" or keeping track of multiple roots, it uncovers many +issues. For example, which content specifically is rolled forward or +backwards? If the package manager isn't deeply aware of a snapshot +tool, it's easy to lose coherency. + +### Filesystem layout + +A concrete example is that rpm-ostree moves the RPM database +to `/usr/share/rpm`, since we want one per root `/usr`. In contrast, +the [snapper](http://snapper.io/) tool goes to some effort to +include `/var/lib/rpm` in snapshots, but +avoid rolling forward/back log files in `/var/log`. + +OSTree requires clear rules around the semantics +of directories like `/usr` and `/var` across upgrades, and +while this requires changing some software, we believe the +result is significantly more reliable than having two separate +systems like yum and snapper glued together, or apt-get and BTRFS, +etc. + +### User experience + +Furthermore, beyond just the mechanics of things like the filesystem +layout, the implemented upgrade model affects the entire user +experience. + +For example, the base system OSTree commits that one replicates from a +remote server can be assigned version numbers. They are +released as coherent wholes, tested together. If one is simply +performing snapshots on the client side, every client machine +can have different versions of components. + +Related to this is that rpm-ostree clearly distinguishes which +packages you have layered, and it's easy to remove them, going back to +a pristine, known state. Many package managers just implement a "bag +of packages" model with no clear bases or layering. As the OS evolves +over time, "package drift" occurs where you might have old, unused +packages lying around. + +# But still evolutionary + +On the other hand, rpm-ostree in other ways is very evolutionary. +There have been many, many different package managers invented - +why not adopt or build on one of those? + +The answer here is that it takes a long time for tooling to be built +on top of a package format - things like mirroring servers. Another +example is source format representations - there are many, many +tools that know how to build source RPMs. + +From the perspective of distribution which has all of that ecosystem +built up, rpm-ostree does introduce a new binary format (ostree), but +otherwise includes an RPM database, and also operates on packages. It +is not a new source format either. +