[ostree] doc: Add a section on deployments

[Colin Walters <walters src gnome org>]

commit d58d6a6ef2a1abfc90a5ab61e485574f1463082e
Author: Colin Walters <walters verbum org>
Date:   Thu Aug 22 08:47:50 2013 -0400

    doc: Add a section on deployments

 doc/Makefile.am     |    1 +
 doc/deployment.xml  |  147 +++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/ostree-docs.xml |    1 +
 3 files changed, 149 insertions(+), 0 deletions(-)
---
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ef1e549..e67b650 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -76,6 +76,7 @@ HTML_IMAGES=
 content_files= \
        overview.xml \
        repo.xml \
+       deployment.xml \
        $(NULL)
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
diff --git a/doc/deployment.xml b/doc/deployment.xml
new file mode 100644
index 0000000..69216e7
--- /dev/null
+++ b/doc/deployment.xml
@@ -0,0 +1,147 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="deployment">
+  <title>Deployments</title>
+  <chapter id="deployment-intro">
+    <title>Overview</title>
+    <para>
+      Built on top of the OSTree versioning filesystem core is a layer
+      that knows how to deploy, parallel install, and manage Unix-like
+      operating systems (accessible via <command>ostree
+      admin</command>).  The core content of these operating systems
+      are treated as read-only, but they transparently share storage.
+    </para>
+
+    <para>
+      A deployment is physically located at a path of the form
+      <filename
+         
class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/deploy/<replaceable>checksum</replaceable></filename>.
+      OSTree is designed to boot directly into exactly one deployment
+      at a time; each deployment is intended to be a target for
+      <literal>chroot()</literal> or equivalent.
+    </para>
+
+  </chapter>
+
+  <chapter id="deployment-osname">
+    <title>"osname": Group of deployments that share /var</title>
+    <para>
+      Each deployment is grouped in exactly one "osname".  From
+      above, you can see that an osname is physically represented in
+      the <filename
+      class='directory'>/ostree/deploy/<replaceable>osname</replaceable></filename>
+      directory.  For example, OSTree can allow parallel installing
+      Debian in <filename
+      class='directory'>/ostree/deploy/debian</filename> and Red Hat
+      Enterprise Linux in <filename
+      class='directory'>/ostree/deploy/rhel</filename> (subject to
+      operating system support, present released versions of these
+      operating systems may not support this).
+    </para>
+
+    <para>
+      Each osname has exactly one copy of the traditional Unix
+      <filename class='directory'>/var</filename>, stored physically
+      in <filename
+      class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/var</filename>.
+      OSTree provides support tools for <command>systemd</command>
+      to create a Linux bind mount that ensures the booted
+      deployment sees the shared copy of <filename
+      class='directory'>/var</filename>.
+    </para>
+
+    <para>
+      OSTree does not touch the contents of <filename
+      class='directory'>/var</filename>.  Operating system components
+      such as daemon services are required to create any directories
+      they require there at runtime (e.g. <filename
+      class='directory'>/var/cache/<replaceable>daemonname</replaceable></filename>),
+      and to manage upgrading data formats inside those directories.
+    </para>
+  </chapter>
+
+  <chapter id="deployment-contents">
+    <title>Contents of a deployment</title>
+    <para>
+      A deployment begins with a specific commit (represented as a
+      SHA256 hash) in the OSTree repository in <filename
+      class='directory'>/ostree/repo</filename>.  This commit refers
+      to a filesystem tree that represents the underlying basis of a
+      deployment.  For short, we will call this the "tree", to
+      distinguish it from the concept of a deployment.
+    </para>
+
+    <para>
+      First, the tree must include a kernel stored as <filename
+      class='directory'>/boot/vmlinuz-<replaceable>checksum</replaceable></filename>.
+      The checksum should be a SHA256 hash of the kernel contents;
+      it must be pre-computed before storing the kernel in the
+      repository.  Optionally, the tree can contain an initramfs,
+      stored as <filename
+      class='directory'>/boot/initramfs-<replaceable>checksum</replaceable></filename>.
+      If this exists, the checksum must include both the kernel and
+      initramfs contents.  OSTree will use this to determine which
+      kernels are shared.  The rationale for this is to avoid
+      computing checksums on the client by default.
+    </para>
+
+    <para>
+      The deployment should not have a traditional UNIX <filename
+      class='directory'>/etc</filename>; instead, it should include
+      <filename class='directory'>/usr/etc</filename>.  This is the
+      "default configuration".  When OSTree creates a deployment, it
+      performs a 3-way merge using the <emphasis>old</emphasis>
+      default configuration, the active system's <filename
+      class='directory'>/etc</filename>, and the new default
+      configuration.  In the final filesystem tree for a deployment
+      then, <filename class='directory'>/etc</filename> is a regular
+      writable directory.
+    </para>
+
+    <para>
+      Besides the exceptions of <filename
+      class='directory'>/var</filename> and <filename
+      class='directory'>/etc</filename> then, the rest of the
+      contents of the tree are checked out as hard links into the
+      repository.  It's strongly recommended that operating systems
+      ship all of their content in <filename
+      class='directory'>/usr</filename>, but this is not a hard
+      requirement.
+    </para>
+  </chapter>
+  
+  <chapter id="managing-boot">
+    <title>The system /boot</title>
+    <para>
+      While OSTree parallel installs deployments cleanly inside the
+      <filename class='directory'>/ostree</filename> directory,
+      ultimately it has to control the system's <filename
+      class='directory'>/boot</filename> directory.  The way this
+      works is via the <ulink
+      url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/";>boot
+      loader specification</ulink>, which is a standard for
+      bootloader-independent drop-in configuration files.
+    </para>
+    <para>
+      When a tree is deployed, it will have a configuration file
+      generated of the form <filename
+      
class='directory'>/boot/loader/entries/ostree-<replaceable>osname</replaceable>-<replaceable>checksum</replaceable>.<replaceable>serial</replaceable>.conf</filename>.
+      This configuration file will include a special
+      <literal>ostree=</literal> kernel argument that allows the
+      initramfs to find (and <literal>chroot()</literal> into) the
+      specified deployment.
+    </para>
+
+    <para>
+      At present, not all bootloaders implement the BootLoaderSpec,
+      so OSTree contains code for some of these to regenerate native
+      config files (such as
+      <filename>/boot/syslinux/syslinux.conf</filename> based on the
+      entries.
+    </para>
+
+  </chapter>
+</part>
diff --git a/doc/ostree-docs.xml b/doc/ostree-docs.xml
index af3fd0c..46b4cd0 100644
--- a/doc/ostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -13,6 +13,7 @@
 
        <xi:include href="overview.xml"/>
        <xi:include href="repo.xml"/>
+       <xi:include href="deployment.xml"/>
 
        <chapter xml:id="reference">
                <title>API Reference</title>