docs: Add an overview section, migrate some content from the wiki

4 files changed, 139 insertions, 4 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 38bc5ded..b5acad6f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -25,7 +25,7 @@ NULL =
 AUTOMAKE_OPTIONS = 1.6
 
 # The name of the module, e.g. 'glib'.
-DOC_MODULE=libostree
+DOC_MODULE=ostree
 
 # The top-level SGML file. You can change this if you want to.
 DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
@@ -73,7 +73,9 @@ HTML_IMAGES=
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=$(NULL)
+content_files= \
+	overview.xml \
+	$(NULL)
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -90,7 +92,7 @@ expand_content_files= \
 GTKDOC_LIBS=
 
 # Hacks around gtk-doc brokenness for out of tree builds
-libostree-sections.txt: $(srcdir)/libostree-sections.txt
+ostree-sections.txt: $(srcdir)/ostree-sections.txt
 	cp $< $@
 
 version.xml:
diff --git a/doc/libostree-docs.xml b/doc/ostree-docs.xml
index 5fdd3d8f..71561acc 100644
--- a/doc/libostree-docs.xml
+++ b/doc/ostree-docs.xml
@@ -7,10 +7,12 @@
 ]>
 <book id="index">
 	<bookinfo>
-		<title>libostree</title>
+		<title>OSTree Manual</title>
 		<releaseinfo>for OSTree &version;</releaseinfo>
 	</bookinfo>
 
+	<xi:include href="overview.xml"/>
+
 	<chapter xml:id="reference">
 		<title>API Reference</title>
 		<xi:include href="xml/libostree-core.xml"/>
diff --git a/doc/libostree-sections.txt b/doc/ostree-sections.txt
index 2e7559ff..2e7559ff 100644
--- a/doc/libostree-sections.txt
+++ b/doc/ostree-sections.txt
diff --git a/doc/overview.xml b/doc/overview.xml
new file mode 100644
index 00000000..2c8e9576
--- /dev/null
+++ b/doc/overview.xml
@@ -0,0 +1,131 @@
+<?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="overview">
+  <title>OSTree Overview</title>
+  <chapter id="ostree-intro">
+    <title>Introduction</title>
+    <para>
+      OSTree is best summarized in a single sentence as "git for
+      operating system binaries".  At its core architecture is a
+      userspace content-addressed filesystem, and layered on top of
+      that is an administrative layer that is designed to atomically
+      parallel install multiple bootable Unix-like operating systems.
+    </para>
+    
+    <para>
+      While it takes over some of the roles of tradtional "package
+      managers" like dpkg and rpm, it is <emphasis>not</emphasis> a
+      package system; nor is it a tool for managing full disk
+      images. Instead, OSTree sits between those levels, offering a
+      blend of the advantages (and disadvantages) of both.
+    </para>
+    
+    <simplesect id="ostree-package-comparison">
+      <title>Comparison with "package managers"</title>
+      <para>
+	Because OSTree is designed for deploying core operating
+	systems, a comparison with traditional "package managers" such
+	as dpkg and rpm is illustrative.  Packages are traditionally
+	composed of partial filesystem trees with metadata and scripts
+	attached, and these are dynamically assembled on the client
+	machine, after a process of dependency resolution.
+      </para>
+      <para>
+	In contrast, OSTree only supports recording and deploying
+	<emphasis>complete</emphasis> (bootable) filesystem trees.  It
+	has no built-in knowledge of how a given filesystem tree was
+	generated or the origin of individual files, or dependencies,
+	descriptions of individual components.
+      </para>
+      <para>
+	The OSTree core emphasizes replicating read-only trees via
+	HTTP.  It is designed for the model where a build server
+	assembles one or more trees, and these are replicated to
+	clients, which can choose between fully assembled (and
+	hopefully tested) trees.
+      </para>
+      <para>
+	However, it is entirely possible to use OSTree underneath a
+	package system; For example, when installing a package, rather
+	than mutating the currently running filesystem, the package
+	manager could assemble a new filesystem tree that includes the
+	new package, record it in the local OSTree repository, and
+	then set it up for the next boot.  To support this model,
+	OSTree provides an (introspectable) C shared library.
+      </para>
+    </simplesect>
+
+    <simplesect id="ostree-block-comparison">
+      <title>Comparison with block/image replication</title>
+      <para>
+	OSTree shares some similarity with "dumb" replication and
+	stateless deployments, such as the model common in "cloud"
+	deployments where nodes are booted from an (effectively)
+	readonly disk, and user data is kept on a different volumes.
+	The advantage of "dumb" replication, shared by both OSTree and
+	the cloud model, is that it's <emphasis>reliable</emphasis>
+	and <emphasis>predictable</emphasis>.
+      </para>
+      <para>
+	But unlike many default image-based deployments, OSTree
+	supports a persistent, writable <literal>/etc</literal> that
+	is preserved across upgrades.
+      </para>
+      <para>
+	Because OSTree operates at the Unix filesystem layer, it works
+	on top of any filesystem or block storage layout; it's
+	possible to replicate a given filesystem tree from an OSTree
+	repository into both a BTRFS disk and an XFS-on-LVM
+	deployment.  Note: OSTree will transparently take advantage of
+	some BTRFS features if deployed on it.
+      </para>
+    </simplesect>
+
+    <simplesect id="ostree-atomic-parallel-installation">
+      <title>Atomic transitions between parallel-installable read-only filesystem trees</title>
+      <para>
+	Another deeply fundamental difference between both package
+	managers and image-based replication is that OSTree is
+	designed to parallel-install <emphasis>multiple
+	versions</emphasis> of multiple
+	<emphasis>independent</emphasis> operating systems.  OSTree
+	relies on a new toplevel <filename
+	class='directory'>ostree</filename> directory; it can in fact
+	parallel install inside an existing OS or distribution
+	occupying the physical <filename
+	class='directory'>/</filename> root.
+      </para>
+      <para>
+	On each client machine, there is an OSTree repository stored
+	in <filename class='directory'>/ostree/repo</filename>, and a
+	set of "deployments" stored in <filename
+	class='directory'>/ostree/deploy/<replaceable>OSNAME</replaceable>/<replaceable>CHECKSUM</replaceable></filename>.
+	Each deployment is primarily composed of a set of hardlinks
+	into the repository.  This means each version is deduplicated;
+	an upgrade process only costs disk space proportional to the
+	new files, plus some constant overhead.
+      </para>
+      <para>
+	The model OSTree emphasizes is that the OS read-only content
+	is kept in the classic Unix <filename
+	class='directory'>/usr</filename>; it comes with code to
+	create a Linux read-only bind mount to prevent inadvertent
+	corruption.  There is exactly one <filename
+	class='directory'>/var</filename> writable directory shared
+	between each deployment for a given OS.  The OSTree core code
+	does not touch content in this directory; it is up to the code
+	in each operating system for how to manage and upgrade state.
+      </para>
+      <para>
+	Finally, each deployment has its own writable copy of the
+	configuration store <filename
+	class='directory'>/etc</filename>.  On upgrade, OSTree will
+	perform a basic 3-way diff, and apply any local changes to the
+	new copy, while leaving the old untouched.
+      </para>
+    </simplesect>
+  </chapter>
+</part>