newbie docs

This commit is contained in:
Joey Hess 2014-04-19 17:08:20 -04:00
parent 7cb414b314
commit 628c06fdfb
3 changed files with 118 additions and 5 deletions

View File

@ -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

View File

@ -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

110
doc/haskell_newbie.mdwn Normal file
View File

@ -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.