It's been exactly six months since we wrote our first Puppet dashboard article and it seems that an update is due.

In this first article, we'll cover installing puppet dashboard on a Debian Lenny server as that is where our puppet server currently runs.

• first of all you will probably need a newer version of the rails framework - use lenny-backports for this:
  • apt-get install -t lenny-backports rails
• now install the puppet-dashboard package by following these instructions

The rest of the install is mostly taken from instructions on the puppet-dashboard repository:

• login to mysql and setup the database (we don't like the generic "dashboard" name):
  • CREATE DATABASE puppetdashboard CHARACTER SET utf8;
  • CREATE USER 'puppetdashboard'@'localhost' IDENTIFIED BY 'my_password';
  • GRANT ALL PRIVILEGES ON puppetdashboard.* TO 'puppetdashboard'@'localhost';
• cd /usr/share/puppet-dashboard
• cp config/database.yml.example config/database.yml
• edit config/database.yml:

  production:
  database: puppetdashboard
  username: puppetdashboard
  host: database_server.example.com
  password: my_password
  encoding: utf8
  adapter: mysql

• the configuration scripts check that the Rake Rubygem is at least v0.8.3, however it doesn't find the installed version so we need to remove that check
  • use "dpkg -s rake" and ensure that you have rake installed and it is at least v0,8.3
  • edit config/environment.rb
    • comment out "config.gem 'rake', :version => '>= 0.8.3'"
• setup the database:
  • rake RAILS_ENV=production db:migrate
• run the (standard, but slow) WEBrick server:
  • ./script/server -e production [-p port]
    • port defaults to 3000, you may need to alter this if it's already in use
• currently there is a missing favicon.ico, so let's fix that (fixed since v1.0.2):
  • wget -O public/images/favicon.ico http://www.puppetlabs.com/favicon.ico

Now point your web browser at the server "http://servername:3000" and you should see the dashboard.

The puppet-dashboard page contains details instructions for setting up puppet to generate reports (search for "Import reports from your puppetmasterd as they're produced"). There are two phases to the process:

• configuring the puppet clients (now called agents) to generate reports
  • This is done by adding "report=true" in the [puppetd] (v0.25) or [agent] (v2.6) section of puppet.conf
  • NB: The documentation currently refers to both agent and agents section. "agents" is incorrect.
• configuring the puppetmaster to send reports to the dashboard
  • for v0.25 the official instructions say to edit libdir on the puppetmaster's puppet.conf file, on Debian Lenny:
    • libdir=/var/lib/puppet/lib:/usr/share/puppet-dashboard/lib
  • this does not work (even on 0.25.5) for many people so instead we suggest in v0.25:
    • mkdir /var/lib/puppet/lib/puppet/reports
    • ln -sf /usr/share/puppet-dashboard/lib/puppet/puppet_dashboard.rb /var/lib/puppet/lib/puppet/reports
    • NB: if your puppet-dashboard is not listening on port 3000, you will have to alter this file
    • In v1.0.3 the file moved to /usr/share/puppet-dashboard/ext/puppet/puppet_dashboard.rb
  • in both cases then edit /etc/puppet/puppet.conf and edit the [puppetmaster] stanza to include "reports=store,puppet_dashboard"
  • in v2.6 edit the [server] stanza of puppet.conf to add:
    • reporturl=http://localhost:3000/reports
    • reports=store,http
• NB: store is not required - it will make the puppetmaster store an additional copy in $reportdir (/var/lib/puppet/reports) so that you can see if there is a problem with reporting or with the import into the puppet dashboard.

Once you have this running, you may wish to import old reports:

• rake RAILS_ENV=production reports:import [REPORT_DIR=/path/to/your/reports]

In our next article we'll take a look at the dashboard itself.