move most of README into the manual

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

3 files changed, 173 insertions, 0 deletions

diff --git a/doc/index.rst b/doc/index.rst
index e48bde5..55c910c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,6 +6,7 @@ Consfigurator user's manual
    :caption: Contents:
 
    introduction
+   installation
    connections
    properties
    hosts
diff --git a/doc/installation.rst b/doc/installation.rst
new file mode 100644
index 0000000..42b23c5
--- /dev/null
+++ b/doc/installation.rst
@@ -0,0 +1,31 @@
+.. _Installation:
+
+Installation
+============
+
+Debian and Debian derivatives
+-----------------------------
+
+The most recent tagged release of Consfigurator is included in `Debian
+experimental`_, and the .deb there should work fine on Debian stable, testing
+and unstable, and derivatives like Ubuntu.  After enabling the repository,
+``apt-get install cl-consfigurator/experimental``.
+
+.. _Debian experimental: https://wiki.debian.org/DebianExperimental
+
+Quicklisp
+---------
+
+The most recent tagged release of Consfigurator is included in the
+`Quicklisp`_ service: ``(ql:quickload "consfigurator")``.
+
+.. _Quicklisp: https://www.quicklisp.org/
+
+From git
+--------
+
+If you would like to follow development more closely, you can::
+
+    % git clone https://git.spwhitton.name/consfigurator ~/.local/share/common-lisp/source/consfigurator
+
+and ASDF should pick it up.
diff --git a/doc/introduction.rst b/doc/introduction.rst
index 1b1e85b..e62f6b6 100644
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@@ -1,6 +1,120 @@
 Introduction
 ============
 
+Try it out / quick start
+------------------------
+
+1. Install Consfigurator: :ref:`Installation`.
+
+2. Create a new directory ``consfig`` somewhere where ASDF will pick it up,
+   such as ``~/common-lisp/consfig``.
+
+3. Define a Lisp system which represents your configuration.
+
+    ~/common-lisp/consfig/com.example.consfig.asd::
+
+        (asdf:defsystem :com.example.consfig
+          :serial t
+          :depends-on (#:consfigurator #:cl-interpol)
+          :components ((:file "package")
+                       (:file "consfig")))
+
+    ~/common-lisp/consfig/package.lisp::
+
+        (in-package :cl-user)
+
+        (defpackage :com.example.consfig
+          (:use #:cl #:consfigurator #:alexandria)
+          (:local-nicknames (#:file      #:consfigurator.property.file)
+                            (#:cmd       #:consfigurator.property.cmd)
+                            (#:data.pgp  #:consfigurator.data.pgp)))
+
+4. Define some hosts and deployments.
+
+    ~/common-lisp/consfig/consfig.lisp::
+
+        (in-package :com.example.consfig)
+        (in-consfig "com.example.consfig")
+	(named-readtables:in-readtable :interpol-syntax)
+
+	(try-register-data-source
+         :pgp :location #P"/path/to/com.example.consfig.gpg")
+
+        (defhost athena.example.com
+	    (:deploy (:ssh (:sudo :as "spwhitton@athena.example.com") :debian-sbcl))
+          "Web and file server."
+	  (file:has-content "/etc/foo" '("these" "are" "my" "lines"))
+	  (file:contains-lines "/etc/some.conf" '("FOO=bar")))
+
+    Here, "spwhitton" is my username on athena; we have to tell Consfigurator
+    what user it will be when it tries to sudo, so it knows whose password it
+    needs.  If you have passwordless sudo access configured, you can skip the
+    ``:AS`` keyword parameter and its argument.
+
+5. Get a Lisp REPL started up -- ``M-x slime`` in Emacs or ``sbcl`` at a shell
+   prompt.  Evaluate ``(asdf:load-system "consfigurator")``.
+
+6. When it's asked to use sudo to become root, Consfigurator will query your
+   registered sources of secrets to try to find the password it will need to
+   give to sudo.  You can easily write code to let Consfigurator query your
+   own sources of secrets, but for the purposes of this guide we'll use the
+   simple, PGP-based secrets source included with Consfigurator.  Unless
+   you've passwordless sudo access set up on athena, evaluate something like
+   this to initialise the store::
+
+     (consfigurator.data.pgp:set-data #P"/path/to/com.example.consfig.gpg"
+                                      "--user-passwd--athena.example.com"
+				      "spwhitton"
+				      "s3cre+")
+
+7. Now you can evaluate ``(asdf:load-system "com.example.consfig")`` followed
+   by ``(in-package :com.example.consfig)`` (or ``C-c ~`` in Emacs).  In the
+   future, now the secrets store exists, you can start with this step.
+
+8. You should now be able to evaluate ``(athena.example.com)`` to deploy
+   properties to athena, using the connection chain of SSH, sudo and then
+   handing over to a remote Lisp image.
+
+Other things to try
+~~~~~~~~~~~~~~~~~~~
+
+Note that some of these violate some of the ideas of declarative configuration
+management, because they apply individual properties without updating the
+definitions of hosts.  Sometimes that's the right thing to do, though, and
+Consfigurator makes it easy to reuse your property definitions in these
+non-declarative ways.
+
+Try deploying properties to athena using a different connection type
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+Evaluate something like::
+
+  (deploy :ssh athena.example.com)
+
+Apply a security update to all your systems
++++++++++++++++++++++++++++++++++++++++++++
+
+It's useful to be able to quickly apply a security update across multiple
+machines without otherwise interacting with their configuration.  Supposing
+you have defined a variable ``*ALL-MY-SERVERS*`` which is a list hosts defined
+with ``DEFHOST``, you can evaluate::
+
+  (dolist (server *all-my-servers*)
+    (deploy-these :ssh server
+                  (cmd:single "apt-get update && apt-get upgrade openssl")))
+
+Regex replace a file across hosts
++++++++++++++++++++++++++++++++++
+
+With ``*ALL-MY-SERVERS*`` as in the previous example,::
+
+  (dolist (server *all-my-servers*)
+    (deploy-these :ssh server
+                  (file:regex-replace-lines "/etc/baz" #?/foo/ "bar")))
+
+(relies on CL-INTERPOL syntax being enabled, as it is in the example consfig
+above)
+
 Concepts and terminology
 ------------------------
 
@@ -135,3 +249,30 @@ recommended package nicknaming schemes for use in consfigs, e.g.::
     (:local-nicknames (#:file        #:consfigurator.property.file)
                       (#:cmd         #:consfigurator.property.cmd)
 		      (#:data.pgp    #:consfigurator.data.pgp)))
+
+Portability and stability
+-------------------------
+
+- **Consfigurator is still stabilising and so there may be lots of breaking
+  changes.**
+
+- All of the code should be portable ANSI Common Lisp, but little to no
+  testing is done by the author on implementations other than SBCL, so testing
+  and portability patches are welcome.
+
+- Little attempt is made by the author to support systems other than Debian
+  GNU/Linux, but again, portability patches are welcome, and the design of
+  Consfigurator should enable supporting other systems.
+
+Credits
+-------
+
+Many of the good ideas here come straight from Joey Hess's Propellor_.  I'm
+working on Consfigurator because I think Propellor is great, but wanted to add
+Consfigurator's POSIX-type connections and arbitrary connection nesting, and I
+wanted to implement that in Lisp (Propellor only supports something equivalent
+to a single, unnested Lisp-type connection).  Additionally, after five years
+of using and extending Propellor, I've come to disagree with Joey about
+whether Haskell's type system helps or hinders using and extending Propellor.
+
+.. Propellor_: https://propellor.branchable.com/