Fixes #5952: Add quickstart for ncf and ncf-builder

site/content/Quickstart.md

@@ -0,0 +1,91 @@
+Title:Quickstart
+
+
+In which we apply our first policy written in ncf.
+
+
+## Install ncf
+
+You will need ncf and CFEngine3 to follow this quickstart.
+
+Add CFEngine repository and install cfengine3:
+
+    wget -qO- https://s3.amazonaws.com/cfengine.package-repos/pub/gpg.key | apt-key add -
+    echo "deb http://cfengine.com/pub/apt/packages stable main" > /etc/apt/sources.list.d/cfengine-community.list
+    apt-get update
+    apt-get install cfengine-community
+
+Add ncf repository and install ncf:
+
+    apt-key adv --recv-keys --keyserver keyserver.ubuntu.com 474A19E8
+    echo "deb http://www.rudder-project.org/apt-latest/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/ncf.list
+    apt-get update
+    apt-get install ncf
+
+Copy the ncf tree to your policy directory:
+
+    cp -r /usr/share/ncf/tree/* /var/cfengine/inputs/ # this is the default directory for cf-agent
+    # you may change the owner to make editing it easier
+
+Use ncf
+-------
+
+You can find ncf documentation at http://www.ncf.io/
+
+Most of your work should go to 50_techniques (generic system configuration methods) and 60_services (final configuration with parameters).
+
+Let's create a technique to force bash timeout on servers:
+
+* Create 50_techniques/shell_timeout/shell_timeout.cf with:
+
+        # @name Force timeout in the shell
+        # @description Force timeout in the shell using TMOUT (bash only)
+        # @version 0.1
+
+        bundle agent shell_timeout(timeout) {
+          vars:
+            "timeout_file" string => "/etc/profile";
+
+          methods:
+            # modify line if it exists
+            "config"  usebundle  => file_replace_lines("${timeout_file}", "^export TMOUT=(?!500$).*", "export TMOUT=${shell_timeout.timeout}");
+            # append it otherwise
+            "config"  usebundle  => file_ensure_lines_present("${timeout_file}", "export TMOUT=${shell_timeout.timeout}");
+        }
+
+* Now we could call this technique from 60_services/baseline/stable/baseline.cf which would be sufficient
+* But instead, create 60_services/servers/stable/servers.cf with:
+
+        bundle agent servers(path)
+        {
+           methods:
+              "any" usebundle => shell_timeout(500);
+        }
+
+* To activate this service in ncf, modify service_mapping.cf and add "/servers/stable" to the "base_services" slist
+
+Test it, run:
+
+    cf-agent -KI
+    grep TMOUT /etc/profile
+
+Yep, it works !
+
+
+Use ncf on a policy server:
+---------------------------
+
+If you want to use ncf with a CFEngine policy server, you only need to install NCF on the server.
+However you still need CFEngine on the client to retrieve and use ncf policies. 
+
+If you do not have a CFEngine server yet, install cfengine on both the client and the server as shown above.
+
+Then on the server:
+
+    /var/cfengine/bin/cf-agent --bootstrap <IP address of self>
+
+And on the client:
+
+    /var/cfengine/bin/cf-agent --bootstrap <IP address of server>
+
+And you must use /var/cfengine/masterfiles instead of /var/cfengine/inputs everywhere in this documentation when installing ncf.

site/content/ncf-builder.md

@@ -0,0 +1,53 @@
+Title: ncf-builder
+
+
+## Install ncf Builder
+
+ncf builder allow you to write techniques easily using a modern web interface.
+
+To setup it you need to install ncf as described in ncf quickstart.
+Then install ncf builder with its dependencies:
+
+	# apt-get install ncf-api-virtualenv apache2 libapache2-mod-wsgi python
+
+If you are on apache 2.4 (debian sid or ubuntu 14.04) move /etc/apache2/conf.d/ncf-api-virtualenv.conf to /etc/apache2/conf-available and run 
+
+	# a2enconf ncf-api-virtualenv
+
+Change ownership of your tree to allow ncf-api to edit it:
+
+	# adduser ncf-api-venv ncf-api-venv
+	# chgrp -R ncf-api-venv /var/cfengine/inputs/
+	# chmod -R g+w /var/cfengine/inputs/
+
+Then restart apache (here on debian, use httpd on rpm based system):
+
+	# service apache2 restart
+
+### Patch ncf-api
+
+The current version (0.201407150059) needs to be patched to remove built-in authentication and to change default path. 
+This won't be necessary in future versions.
+
+Edit /usr/share/ncf-api-virtualenv/ncf_api_flask_app.wsgi to remove built-in authentication:
+	Line 41     : available_modules_name = ["Rudder"] 
+	Replace with: available_modules_name = []
+
+Edit /usr/share/ncf-api-virtualenv/ncf_api_flask_app.wsgi to change default path, this change must be done on all 4 path checks.
+Be careful, the test content change, do not paste as is: 
+	Change: if "path" in request.args:
+	To    : if "path" in request.args and request.args['path'] != "":
+
+And replace the default path to your CFEngine policies path, this is done in the else section:
+	Change: path = ""
+	To    : path = "/var/cfengine/inputs/" # your test path
+
+Repeat on line 64, 78, 97, 114 and restart apache.
+
+### Test ncf Builder
+
+Now simply go to http://localhost/ncf-builder/ and add or modify your techniques.
+
+Please be aware that for now this editor only edit *techniques*, you still need to write or modify a *service* file to call them from ncf.
+
+Enjoy !