The Puppet Dashboard is a new project from Reductive Labs that's really turning out to be a Swiss-Army knife for puppetmasters.  Not only can you track node successes, failures, and runtime, but you can use it as an External Node Classifier tool too.  It's quite simple to get up running once you figure out the basics.  This article deals with installing the Puppet Dashboard on OS X Server version 10.5.8.  Most of these commands will need to be run as the superuser - so I'm assuming you're either doing a sudo -s at the beginning or running them with sudo.

Setup and Start MySQL:

You'll first need to download the MySQL binaries since Apple chooses not to include them.  Visit Apple's Support page and follow the install instructions to the letter.  MAKE SURE you download the binaries for Leopard Server.

Next, open Server Admin and add the MySQL Service to your service list by first clicking directly on your server's hostname, clicking the Settings button, clicking the Services tab, and then checking the box next to MySQL.  Hit the save button in the bottom right to bring up MySQL in your list of services (toggle the triangle next to your server's hostname to see your list of services).

Click on the MySQL service, and then on the Settings button - you should then see your Database location (/var/mysql) in the textbox below.  Click the Set MySQL Root Password button to change the root password to something secure and then click the save button at the bottom.  

Finally, click the Start MySQL button at the bottom to start the service.

Update and Install Ruby Gems

Puppet Dashboard makes use of the rake and mysql ruby gems, so we'll need to make sure those are installed.  Do this by executing the following commands:

gem update

gem install rake

gem install mysql

Note that updating your gems MAY break a dependency if you rely on certain versions of ruby gems.  If you're installing this on a machine that leverages ruby gems, take caution in running the first command.  There is one more gem associated with rake that need be installed, but we will do this in a later step

Get the Puppet Dashboard source from Github

I'm assuming that you've already installed git if you're proceeding through this tutorial.  If you've not, visit Github and follow the instructions for downloading and installing Git.  It's a package installation, so it's fairly trivial.  After git is installed, download the puppet source with the following commands

cd /etc

git clone git://github.com/reductivelabs/puppet-dashboard.git 

This creates a puppet-dashboard directory inside your /etc directory with the Puppet Dashboard source code.  You may need to run the git clone command as the superuser with the sudo command.  

Modify Dashboard MySQL Config and Download one more gem

At this point you can create a user in MySQL for puppet dashboard (which is probably more secure than using the root user) OR use the root user for puppet dashboard to create its tables.  I'll leave that up to you - either way you'll need a username/password for MySQL to proceed.  Let's create a database config file and install the last rake gem with the following commands:

cd /etc/puppet-dashboard

cp config/database.yml.example config/database.yml

rake gems:install

We've copied the database config file, now let's edit it.  Open /etc/puppet-dashboard/config/database.yml with your favorite command line text editor and edit the username: line in every database declaration (substituting your MySQL user if you've created one).  You'll also need to add a password: line underneath the username: line and insert the password you've created.  

The rake command should automatically install the has_scope gem that is usually missing.

Install and Start the Puppet Dashboard

Now we can actually start the installation process and start the Puppet Dashboard.  Do that with the following commands:

cd /etc/puppet-dashboard

rake install

script/server

If everything goes well, it will start the dashboard at http://localhost:3000 - open it up and try it out!  

Setting up a Launch Daemon for Puppet Dashboard and MySQL

From here, if everything works correctly, we can choose to setup a launchd .plist to launch the Puppet Dashboard. Save the following as /Library/LaunchDaemons/com.reductivelabs.puppetdashboard.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>com.reductivelabs.puppetdashboard</string>
	<key>ProgramArguments</key>
	<array>
		<string>/etc/puppet-dashboard/script/server</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
</dict>
</plist>

Next, we need to make sure that MySQL is also loaded at Startup. Do this by running:

sudo launchctl load -w /System/Library/LaunchDaemons/org.mysql.mysqld.plist 

this will load the MySQL LaunchDaemon. Once that's done, you can then run the following command to load the dashboard LaunchDaemon we created in the previous step:

sudo launchctl load -w /Library/LaunchDaemons/com.reductivelabs.puppetdashboard.plist

Enabling Live Reporting with Puppet Dashboard

The beauty of Puppet Dashboard is that it can automatically receive reporting information from your clients and store it in a MySQL DB for easy retrieval. To do this, we need to move a script and set a couple of things in the puppet.conf on the server. In /etc/puppet-dashboard/lib/puppet there exists a script called puppet_dashboard.rb. We will need to copy this to our $libdir/puppet/reports directory. On 10.5 Server, you can do that like this:

cp /etc/puppet-dashboard/lib/puppet/puppet_dashboard.rb /Library/Ruby/Site/1.8/puppet/reports/puppet_dashboard.rb

chmod 755 /Library/Ruby/Site/1.8/puppet/reports/puppet_dashboard.rb

This copies the script to the appropriate location and makes it executable. Next, let's open /etc/puppet/puppet.conf and add the following line in the [puppetmasterd] section:

reports = puppet_dashboard

This tells our server to call the puppet_dashboard script when a client provides report data. Finally, you need to make sure the client puppetd binary is run with the --report argument so that it will SEND report data. Once everything is set, you can restart your puppetmasterd service (if running Passenger, do this by running apachectl restart from the command line).

Importing Report Records

If you've already had reporting enabled on the Puppetmaster, and you have a directory full of reports, you can import those at any time. First, you'll have to edit etc/puppet-dashboard/lib/tasks/import_reports.rake and modify the DEFAULT_DIR variable to point to your reports directory. Once that change has been made, change to the /etc/puppet-dashboard directory and run the following:

rake reports:import

Your reports should import into the Puppet Dashboard and life should be good!