From 628c06fdfba15f087baa844ca14a16a233c2b301 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sat, 19 Apr 2014 17:08:20 -0400 Subject: newbie docs --- doc/haskell_newbie.mdwn | 110 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 doc/haskell_newbie.mdwn (limited to 'doc/haskell_newbie.mdwn') 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