diff options
authorJoey Hess2014-04-19 17:08:20 -0400
committerJoey Hess2014-04-19 17:08:20 -0400
commit628c06fdfba15f087baa844ca14a16a233c2b301 (patch)
parent7cb414b3146fff486fd1d1a2c08199218338a0a9 (diff)
newbie docs
3 files changed, 118 insertions, 5 deletions
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 ""
& Apt.stdSourcesList Unstable
- `onChange` Apt.upgrade
& Apt.unattendedUpgrades
& Apt.installed ["etckeeper"]
& Apt.installed ["ssh"]
@@ -42,6 +44,3 @@ hosts =
-- add more hosts here...
--, host "" = ...
-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]( 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](
## 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](
+[[!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 ""
+ & Apt.stdSourcesList Unstable
+ , host ""
+ & 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
+ 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 "" & 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.
+ 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.