newbie docs

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

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

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.
+
+<pre>
+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"]'
+</pre>
+
+Similarly, if you make a typo in the config file, you'll probably get a long
+but informative error message.
+
+<pre>
+config-simple.hs:27:19:
+    Not in scope: `Apt.standardSourcesList'
+    Perhaps you meant one of these:
+      `Apt.stdSourcesList' (imported from Propellor.Property.Apt)
+...
+</pre>
+
+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.