NOTE May 2012. The documentation below refers to old versions of the Example42 Puppet Modules and sample Infrastructures. You can still use them but be sure to git clone the correct branch versions (1.0 and 2011 respectively).

The setup of Puppet for a beginner is not always easy. You have to install and configure the PuppetMaster and the Puppet clients, exchange and sign their certificates and then start to write Puppet code in order to see something interesting happening.

To install the Puppet Master is not difficult but you need some tweaks in order to activate specific features and functionalities. With the Example 42 puppet module you can easily setup a PuppetMaster with the following features:
- Integration with the web frontends Dashboard or the Foreman with or without external nodes.
- Support for 0.25 and 2.6 versions
- Support for storeconfigs (full and thin)
- Support for Apache Mod Passenger and Mysql database backend
- Support for these distro: RedHat/Centos, Debian/Ubuntu.

 First of all you have to install Puppet and Git packages, following the procedures needed for your Operating System. Then you can clone the Example42 modules and infrastructures repository (you might need to rename or remove the directories /etc/puppet/modules and /etc/puppet/manifests if they already exist):

git clone --recursive -b 1.0 git://github.com/example42/puppet-modules.git /etc/puppet/modules
git clone --recursive -b 2011 git://github.com/example42/puppet-infrastructures /etc/puppet/manifests

Then you can edit the Example42 PuppetMaster Toaster manifest and set there the variables you need.

Note that, even if this file uses normal Puppet language is intended to be used in "masterless" mode, via a direct puppet command run, as shown below.

vi /etc/puppet/manifests/toasters/puppet/init.pp

There are different variables that you can set in order to obtain the setup you prefer. The most important ones are:

$puppet_server (default: "puppet") - Defines the hostname of the puppet master. Set it to the fqdn of your PuppetMaster (the preferred choice is to call it puppet.yourdomain.com)

$puppet_allow (default: "*.$domain" , "127.0.0.0") - Defines the acls on PuppetMaster's fileserver.conf. Put here the networks or domain names of your Puppet clients.

$puppet_nodetool (default: undefined) - Use to install an external web interface ("dashboard" or "foreman" are the possible values) which can be used for reporting or as an external node classifier (see next option).

$puppet_externalnodes (default: no) - Use the specified nodetool as external node classifier (if "yes" here, $puppet_nodetool must be defined). If set to yes your nodes, variables and classes are defined in the chosen web interface instead of normal Puppet manifests (as the example ones provided in the Example42 Puppet Infrastructures).

$puppet_passenger (default: no) - Use Apache's mod ruby (Passenger) instead of default Webric. This is a preferred choice for medium/large installations.You might prefer the default, more straightforward, choice for test beds or small installations (less than 100 nodes).

$puppet_storeconfigs (default: no) - Use storeconfigs, a feature that requires the use of a database (SQLLite or MySQL are the supported alternatives here) to save data related to the nodes. This option is needed when you use exported resources (as in Example42's Monitoring classes) but can heavily impact on the PuppetMaster performances.

$puppet_storeconfigs_thin (default: yes) - Use thin storeconfigs, a "lighter" usage of storeconfigs with less performance issues but the same support for exported resources. This is a sub-options, it still needs $puppet_storeconfigs = yes to be activated.

$puppet_db (default: sqlite) - The Database backend to use if you activate storeconfigs ("sqlite" or "mysql" are the possible values, the former should be used only in test beds or very small installations).

$puppet_db_server (default: localhost) ,  $puppet_db_user (default: root) , $puppet_db_password (default: undefined)  control the database access credentials when using MySql.

Once edited the toasters/puppet/init.pp file with the settings you want, you can run Puppet on it:

puppet -v /etc/puppet/manifests/toasters/puppet/init.pp

Here starts the Puppet dance that might last some minutes while packages are installed (we imply that the system has Internet access or, in any case, can install packages with its tools such as apt-get or yum), files are configured and things are generally done.
If there have been dependencies issues (should not), you may need to re-run the above Puppet command , as many times as needed, until nothing new happens, and at the end you have your Puppet Master setup.

Now begins the fun:
- If you have set $puppet_externalnodes to yes browser to http://puppet.your.domain.com:3000 and start to add nodes, variables and include classes from there.
- Otherwise look at /etc/puppet/manifests/site.pp (the first file the PuppetMaster looks at when it has to compile the catalog for its clients: from here everything begins). The one provided with Example42 Infrastructures you cloned earlier imports other manifests (.pp) where are defined example nodes, that include classes and set variables used by these classes. Check the modules' README for more info on the variables each module accepts and change the nodes names according to your clients' fqdns.

- Then on your clients, you can install the Puppet package, and run puppet:

puppetd -t 

or, if your PuppetMaster cannot be resolved as "puppet"

puppetd -t --server=mypuppetmasterhost.domain.com

The first time you run this command no resources are applied, because the client's certificate has not been signed by  the PuppetMaster. Go on the PuppetMaster host and write:

puppetca -l

to see the current certificates requests, and to sign one type:

puppetca -s clienthostname.domain.com

Now you can finally run again puppetd -t on the client and see what Puppet has been configured to do on your node.