From 3221452e18b8cbb3d09ae4daee5da7364222b2d7 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sun, 14 Feb 2021 10:59:21 -0700 Subject: add examples to README Signed-off-by: Sean Whitton --- README.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 8 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 91ed043..0b7ddb2 100644 --- a/README.rst +++ b/README.rst @@ -5,16 +5,52 @@ 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. -Many or all of the good ideas here come straight from Joey Hess's Propellor_. -I'm working on Consfigurator mainly because I think Propellor is great and -reimplementing those ideas is good practice in writing Common Lisp, but also -because 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. +Quick start / introduction +========================== -.. Propellor_ https://propellor.branchable.com/ +1. 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. + + ~/common-lisp/consfig/com.example.consfig:: + + (asdf:defsystem :com.example.consfig + :serial t + :depends-on (#:consfigurator) + :components ((:file "package") + (:file "consfig"))) + + ~/common-lisp/consfig/package.lisp:: + + (in-package :cl-user) + + (defpackage :com.example.consfig + (:use #:cl #:consfigurator) + (:local-nicknames (#:file #:consfigurator.property.file))) + +3. Define some hosts and connections. + + ~/common-lisp/consfig/consfig.lisp:: + + (in-package :com.example.consfig) -Portabiilty and stability + (setconsfig :com.example.consfig) + + (defhost athena.example.com + "Web and file server." + (file:contains-lines "/etc/default/locale" '("LANG=en_GB.UTF-8"))) + + (defhostdeploy :ssh athena.example.com) + +4. Get a Lisp REPL started up and 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. + +Portability and stability ========================= - **Consfigurator is still stabilising and so there may be breaking changes.** @@ -25,3 +61,16 @@ Portabiilty and stability - No attempt is made to support running on Windows -- we often eschew Common Lisp pathnames in favour of simple strings with forward slashes as directory separators. + +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_ https://propellor.branchable.com/ -- cgit v1.2.3