Pro Puppet (37 page)

We don't recommend installing the Dashboard from source because packages are much easier to manage and update, but it is possible. You can download a tarball from the Puppet Labs Download page:

You can then unpack the tarball in an appropriate directory, for example:

Alternately, you can clone the current Dashboard source code from GitHub. You will need to have installed Git to clone the required repository:

You can then change into the resulting directory:

And continue installing the Dashboard.

Once you have installed Puppet Dashboard, you need to create a database to hold the Dashboard's data, configure that database in the Dashboard and populate that database with the appropriate tables. This is a three-step process:

1. Edit the YAML configuration file (
   database.yml
) to specify the database
   
2. Create the database “Dashboard” with the Ruby
   rake
command based on the edited configuration file
   
3. Populate the database
   

We start by editing the
/usr/share/puppet-dashboard/config/database.yml
file, which specifies our database configuration.

The database.yml file is a YAML configuration file and any settings we specify in the file need to be valid YAML.

Ruby on Rails applications use the concept of environments (production, development, etc.) to allow you to specify multiple databases and configurations for different purposes in a single application. For our purposes, we're just going to create a single environment for a production Dashboard instance, as you can see in
Listing 7-1
.

The
database.yml
file contains a series of database configurations for the different Rails environments. Inside each environment block we need to specify the name of the database we're using, the username and password used to connect to that database, as well as the encoding and database type. In this case, we're going to leave all of the default settings except the password. Select an appropriate password and save the file.

We're now going to use the Ruby
rake
command to automatically create a database based on the configuration in the
database.yml
file. To do this we need to change to the root of the Dashboard. Assuming we've used the package installation, that would be
/usr/share/puppet-dashboard
:

Now run a
rake
command, like so:

This will create a database called “
dashboard,
” with a user of
dashboard
secured with the password you specified in the
database.yml
configuration file.

You could also manually create the database using the MySQL command line interface, for example:

$ sudo mysql –p
mysql> CREATE DATABASE dashboard CHARACTER SET utf8; CREATE USER 'dashboard'@'localhost'
 IDENTIFIED BY 'password'; GRANT ALL PRIVILEGES ON dashboard.* TO 'dashboard'@'localhost';


After you've created the database, you then need to populate this database with the appropriate tables. To do this, use another
rake
command. First make sure you're in the root of the Puppet Dashboard application, then run the required
rake
task.

Once you have the Dashboard database configured, you can run it. Puppet Dashboard is a Ruby on Rails application that can be run in a number of different ways, such as using the internal Webrick server or via integration with a server like Passenger (which we talked about in
Chapter 4
). Webrick is a good way to quickly get started with the Dashboard, but it doesn't scale very well and performs poorly when you have a large number of Puppet agents reporting to the Dashboard. We recommend using a server like Passenger to run the Dashboard, it is a better performing and scalable solution than the internal Webrick server.

In the next two sections, we're going to show you how to use either the Webrick server or Passenger to run the Dashboard.

Running with the built-in Webrick web server is very simple; indeed, the init scripts provided with the Dashboard packages do exactly this. However, there are some important limitations to consider with Webrick. It's quite slow and can't easily handle multiple simultaneous requests.

To run the Webrick server, change into the root of the Dashboard application:
/usr/share/puppet-dashboard
and run:

This will run the Webrick server on port 3000. You can now browse to your host, for example
http://dashboard.example.com:3000
and view the Dashboard.

Or you can run the init script that comes with the Puppet Dashboard package like so:

Passenger is rather more sophisticated and far better performing than Webrick, and it can be combined with Apache or Nginx. We're going to show you integration with Apache, but we'll provide you some resources where you can read about how to integrate with Nginx too. The main advantage of Passenger is that it is drastically faster and more scalable than Webrick as an engine for running the Dashboard.

Running Passenger, however, is somewhat more complex than using Webrick. It requires a web server, which Passenger integrates with as a module, and then some further configuration on the Dashboard side. We're going to take you through the steps required to:

• Install any prerequisite packages including Apache and Passenger
  
• Configure an Apache virtual host to run Passenger and the Dashboard
  

Our first step is to install the required prerequisite packages. This includes Apache, the MySQL Ruby bindings and Passenger itself.

Red Hat

On Red Hat and related distributions, this involves installing the following packages (we've assumed you've still got the EPEL repository enabled):

Unfortunately, Passenger is not yet available for Red Hat as a package due to some packaging issues. We can however install Passenger from a gem, for example:

Once we've installed the Ruby Gem we need to use the
passenger-install-apache2-module
script to create the required Apache Passenger module.

Follow the provided instructions to create and install the Apache Passenger module.

Ubuntu and Debian

On Ubuntu and Debian, the required packages are:

You might have already installed some of these packages, either to run Puppet or earlier in this chapter when you were setting up the Dashboard.