README enhancement

diff --git a/README b/README
index a5c4a87b5ca904056925f8a18499bc7370da73d2..1879a0672ad154c82551097257950918baadba87 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,48 @@
 Sarava's Ikiwiki Puppet Module
 ==============================
 
-This is an attempt to make a simple and straightforward puppet module to manage ikiwiki instances.
+This is an attempt to make a simple and straightforward puppet module to manage ikiwiki instances
+leveraging a git daemon such as gitolite.
 
 Gitolite or gitosis is needed but should be managed elsewhere. Please setup your keys before deploying
 the instances.
+
+How it works
+------------
+
+The following setup is used:
+
+  - Wiki pages are served under it's own user, but the cgi usually runs under www-data.
+  - The git daemon runs on its own user and group.
+
+So the recommended suid for the cgi and the post update hook are used normally.
+
+For that to work, you, the wiki user and root needs ssh read/write access to the git daemon:
+
+  - You need to be able to push an pull changes to the git daemon.
+  - The cgi backend also needs push and pull access to the bare repository.
+  - Gitolite needs permission to write into the repository working copy and be able to generate pages.
+  - Root also needs access to the repo so "ikiwiki --setup" can be run as root.
+
+Usage example
+-------------
+
+  # Declare the ikiwiki class
+  class { 'ikiwiki': }
+
+  # Define your website using your http server module of choice.
+  apache::site { "mywiki":
+    docroot => "${apache::sites_folder}/mywiki/ikiwiki",
+    use     => [ "Ikiwiki mywiki" ],
+    owner   => 'mywiki',
+    group   => 'mywiki',
+  }
+
+  # Define your ikiwiki instance.
+  ikiwiki::instance { "mywiki":
+    ensure          => present,
+    description     => "My Ikiwiki",
+    adminuser       => "myuser",
+    disable_plugins => "openid",
+    add_plugins     => "goodstuff sidebar",
+  }