From 628c06fdfba15f087baa844ca14a16a233c2b301 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sat, 19 Apr 2014 17:08:20 -0400 Subject: newbie docs --- config-simple.hs | 7 ++- doc/README.mdwn | 6 ++- doc/haskell_newbie.mdwn | 110 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 118 insertions(+), 5 deletions(-) create mode 100644 doc/haskell_newbie.mdwn diff --git a/config-simple.hs b/config-simple.hs index 23a760c8..536d9cd5 100644 --- a/config-simple.hs +++ b/config-simple.hs @@ -16,13 +16,15 @@ import qualified Propellor.Property.User as User --import qualified Propellor.Property.Tor as Tor import qualified Propellor.Property.Docker as Docker +main :: IO () +main = defaultMain hosts + -- The hosts propellor knows about. -- Edit this to configure propellor! hosts :: [Host] hosts = [ host "mybox.example.com" & Apt.stdSourcesList Unstable - `onChange` Apt.upgrade & Apt.unattendedUpgrades & Apt.installed ["etckeeper"] & Apt.installed ["ssh"] @@ -42,6 +44,3 @@ hosts = -- add more hosts here... --, host "foo.example.com" = ... ] - -main :: IO () -main = defaultMain hosts diff --git a/doc/README.mdwn b/doc/README.mdwn index f463cfa5..eec3d76f 100644 --- a/doc/README.mdwn +++ b/doc/README.mdwn @@ -5,7 +5,8 @@ are satisfied. Propellor is configured via a git repository, which typically lives in `~/.propellor/` on your development machine. Propellor clones the -repository to each host it manages, in a [[secure|security]] way. +repository to each host it manages, in a +[secure](http://propellor.branchable.com/security/) way. To trigger propellor to run on a host, run `propellor --spin $host`. Or run `/usr/local/propellor/propellor` on the host. Or use the @@ -21,6 +22,9 @@ the full power of Haskell. Hopefully that power can be put to good use in making declarative properties that are powerful, nicely idempotent, and easy to adapt to a system's special needs! +If using Haskell to configure Propellor seems intimidating, +see [configuration_for_the_Haskell_newbie](https://propellor.branchable.com/haskell_newbie/). + ## quick start 1. Get propellor installed diff --git a/doc/haskell_newbie.mdwn b/doc/haskell_newbie.mdwn new file mode 100644 index 00000000..e96a591b --- /dev/null +++ b/doc/haskell_newbie.mdwn @@ -0,0 +1,110 @@ +Propellor's config file is written in Haskell, and Haskell is +invaluable to extend Propellor with your own custom properties. But you +don't need to know about monads to configure Propellor! + +Let's take a quick tour of the `config.hs` file.. + +[[!format haskell """ +-- | This is the main configuration file for Propellor, and is used to build +-- the propellor program. +"""]] + +So, `-- ` starts a comment in this file. + +[[!format haskell """ +import Propellor +import Propellor.CmdLine +import qualified Propellor.Property.File as File +import qualified Propellor.Property.Apt as Apt +import qualified Propellor.Property.User as User +import qualified Propellor.Property.Cron as Cron +"""]] + +This loads up Propellor's modules. You'll almost certianly want these; +many more can be found in the [API documentation](http://hackage.haskell.org/package/propellor). + +[[!format haskell """ +main :: IO () +main = defaultMain hosts +"""]] + +This config file *is* the Propellor program, and so it needs a little +stub to go run itself. No need to ever change this part. +`hosts` is the list of hosts that you configure, and it comes next: + +[[!format haskell """ +-- The hosts propellor knows about. +-- Edit this to configure propellor! +hosts :: [Host] +hosts = + [ host "mybox.example.com" + & Apt.stdSourcesList Unstable + , host "server.example.com" + & Apt.stdSourcesList Stable + & Apt.installed ["ssh"] + ] +"""]] + +This defines a list of hosts, with two hosts in it. + +The configuration for the mybox host tells propellor to configure its +`/etc/apt/sources.list` to use Debian `Unstable`. +Of course you might want to change that to `Stable`. + +Each property of the host is prefixed with an "&" operator. This just makes +a list of properties. Above, the first host has only 1 property, while +the second host has 2 properties. + +Some other properties you may find in your config.hs, or want to add: + +[[!format haskell """ + & Apt.unattendedUpgrades + & User.hasSomePassword "root" + & Cron.runPropellor "30 * * * *" +"""]] + +Some of these properties can be reverted -- this makes Propellor undo whatever +effects they might have. For example, unattended upgrades can be scary, so +maybe you turned that on, but want to disable it now. To do so, just change +the "&" to a "!" + +[[!format haskell """ + ! Apt.unattendedUpgrades +"""]] + +Some properties cannot be reverted. Yet. It takes coding to implement +revertability. If you try to revert a property that does not support +reversion, propellor will **fail to compile**! This is a good thing.. +it avoids you getting confused or bad things happening. + +The error message when this happens might look a little scary. But if +you read through it, it's remarkably precise about what and where the problem +is. + +
+config-simple.hs:30:19:
+    Couldn't match expected type `RevertableProperty'
+                with actual type `Property'
+    In the return type of a call of `Apt.installed'
+    In the second argument of `(!)', namely `Apt.installed ["ssh"]'
+    In the first argument of `(&)', namely
+      `host "mybox.example.com" & Apt.stdSourcesList Unstable
+       & Apt.unattendedUpgrades
+       ! Apt.installed ["ssh"]'
+
+ +Similarly, if you make a typo in the config file, you'll probably get a long +but informative error message. + +
+config-simple.hs:27:19:
+    Not in scope: `Apt.standardSourcesList'
+    Perhaps you meant one of these:
+      `Apt.stdSourcesList' (imported from Propellor.Property.Apt)
+...
+
+ +That's really all there is to configuring Propellor. Once you +have a `config.hs` ready to try out, you can run `propellor --spin $host` +on one of the hosts configured in it. See the [[README]] for a further +quick start. -- cgit v1.2.3