From 093dda153d48e41d2646222f58e95f6e163696ac Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Tue, 16 Feb 2021 14:49:17 -0700 Subject: fill out README with some more general description and some fixes Signed-off-by: Sean Whitton --- README.rst | 63 +++++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 15 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 0b7ddb2..c42256f 100644 --- a/README.rst +++ b/README.rst @@ -3,17 +3,49 @@ Introduction Consfigurator is a system for declarative configuration management using Common Lisp. You can use it to configure hosts as root, deploy services as -unprivileged users, and build disc images. +unprivileged users, build and deploy containers, and produce disc images. + +Consfigurator's design gives you a great deal of flexibility about how to +control the hosts you want to configure. Input and output streams attached to +an interactive POSIX sh running on the target host (or in the target +container) is sufficient to use much of Consfigurator's functionality. But if +it is possible to get an implementation of Common Lisp started up on the host, +then Configurator can transparently execute your deployment code over on the +remote side, rather than exchanging information via POSIX sh. This lets you +use the full power of Common Lisp to deploy your configuration. + +Configurator has convenient abstractions for combining these different ways to +execute your configuration on hosts with different ways of connecting to them. +Connections can be arbitrarily nested. For example, to combine SSHing to a +Debian machine as an unprivileged user, using sudo to become root, and then +starting up a Lisp process to execute your deployment code, you would just +evaluate ``(deploy (:ssh (:sudo :user "root") :debian-sbcl) foo.example.com)``. + +Declarative configuration management systems like Consfigurator and Propellor_ +share a number of goals with projects like the `GNU Guix System`_ and +`NixOS`_. However, tools like Consfigurator and Propellor try to layer the +power of declarative and reproducible configuration on top of traditional, +battle-tested unix system administration infrastructure like apt, dpkg, yum, +and distro package archives, rather than seeking to replace any of those. +Let's get as much as we can out of all that existing distro policy-compliant +work! + +.. _Propellor: https://propellor.branchable.com/ +.. _GNU Guix System: https://guix.gnu.org/ +.. _NixOS: https://nixos.org/ Quick start / introduction ========================== -1. Create a new directory ``consfig`` somewhere where ASDF will pick it up, +1. Install Steel Bank Common Lisp and Consfigurator. One way to do the latter + is to clone this git repository into ``~/.local/share/common-lisp/source``. + +2. Create a new directory ``consfig`` somewhere where ASDF will pick it up, such as ``~/common-lisp/consfig``. -2. Define a Lisp system which represents your configuration. +3. Define a Lisp system which represents your configuration. - ~/common-lisp/consfig/com.example.consfig:: + ~/common-lisp/consfig/com.example.consfig.asd:: (asdf:defsystem :com.example.consfig :serial t @@ -29,7 +61,7 @@ Quick start / introduction (:use #:cl #:consfigurator) (:local-nicknames (#:file #:consfigurator.property.file))) -3. Define some hosts and connections. +4. Define some hosts and connections. ~/common-lisp/consfig/consfig.lisp:: @@ -43,12 +75,13 @@ Quick start / introduction (defhostdeploy :ssh athena.example.com) -4. Get a Lisp REPL started up and evaluate ``(asdf:require-system - "com.example.consfig")``. +5. Get a Lisp REPL started up -- ``M-x slime`` in Emacs or ``sbcl`` at a shell + prompt. Evaluate ``(asdf:require-system "com.example.consfig")``. -5. Now you should be able to use configure athena by evaulating - ``(athena.example.com)``. You can use the DEPLOY function to try out - configuring athena using a different connection type than defined here. +6. Now you should be able to use configure athena by evaulating + ``(com.example.consfig:athena.example.com)``. You can use the + ``CONSFIGURATOR:DEPLOY`` function to try out configuring athena using a + different connection type than defined here. Portability and stability ========================= @@ -68,9 +101,9 @@ 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`` connections and arbitrary connection nesting -- -Propellor supports something equivalent to a single ``:lisp`` connection -- -and I wanted to implement that in Lisp. Also, 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 supports something equivalent to a single, unnested ``:lisp`` +connection -- and I wanted to implement that in Lisp. Also, 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/ +.. Propellor_: https://propellor.branchable.com/ -- cgit v1.2.3