Puppet Dashboard Manual(Generated on July 01, 2013, from git revision 46784ac1656bd7b57fcfb51d0865ec7ff65533d9)
Puppet Dashboard 1.2 ManualThis is the manual for Puppet Dashboard 1.2.
OverviewPuppet Dashboard is a web interface for Puppet. It can view and analyze Puppet reports, assignPuppet classes and parameters to nodes, and view inventory data and backed-up file contents.
ChaptersInstalling DashboardUpgrading DashboardConfiguring DashboardMaintaining DashboardUsing DashboardRake API
Installing Puppet DashboardThis is a chapter of the Puppet Dashboard 1.2 manual.NAVIGATION
Installing DashboardUpgrading DashboardConfiguring DashboardMaintaining DashboardUsing DashboardRake API
OverviewPuppet Dashboard is a Ruby on Rails web app that interfaces with Puppet. It will run on mostmodern Unix-like OSes (including Mac OS X and most Linux distributions), requires a certainamount of supporting infrastructure, and can be deployed and served in a variety of ways.Dashboards web interface supports the following browsers:
Chrome (current versions)Firefox 3.5 and higher
Puppet Dashboard Manual Puppet Dashboard 1.2 Manual 2/27
Safari 4 and higherInternet Explorer 8 and higher
Installing, in SummaryIn outline, the steps to get Dashboard running are:
Installing the external dependenciesInstalling the Dashboard codeConfiguring DashboardCreating and configuring a MySQL databaseTesting that Dashboard is workingConfiguring PuppetStarting the delayed job worker processesRunning Dashboard in a production-quality server
After completing these tasks, Dashboards main functionality will be on-line and working smoothly.You can then configure Dashboard further and enable optional features
If you are trying to upgrade Puppet Dashboard instead of installing it from scratch, see the chapterof this manual on upgrading instead of reading further in this chapter. If youre looking for a vastlysimplified installation and maintenance process, download a free trial of Puppet Enterprise and tryits improved and extended web console.
Installing DependenciesDashboard is distributed with the version of Rails it uses, as well as most of its other dependencies,but youll have to ensure that the following software is installed:
RubyGemsRake version 0.8.3 or newerMySQL database server version 5.xRuby-MySQL bindings version 2.7.x or 2.8.x
On most OSes, youll be able to install all of these easily with the OSs package tools.
Note: Puppet supplies Ruby 1.8.7 packages for Enterprise Linux 5 and its variants in order meet theRuby versioning requirement for Dashboard. Also note, these packages replace existing Rubypackages in your system.INSTALLING DEPENDENCIES UNDER UBUNTU 10.04 LTS
Due to issues with Ubuntu 10.04 LTSs version of Ruby, you can install most dependencies frompackages but must manually build gem . Additionally, if you encounter performance issues, you maywish to manually upgrade your version of Ruby to patch level 299 or higher.Puppet Dashboard Manual Puppet Dashboard 1.2 Manual 3/27
These instructions assume a fresh install of the OS, and may differ depending on its currentconfiguration. The commands must be run from one of the standard shells, preferably bash , dash ,or zsh .
Installing Puppet DashboardYour three options for installing Dashboard are to use the Puppet Labs package repositories, installthe source from Git, or download a tarball of the source. Whichever way, youll end up with a singledirectory as Rails apps are self-contained, all of Dashboards code, configuration, and run datawill be stored in the same area. Any rake tasks mentioned later in this manual should be performedfrom a shell in this main directory, and any relative paths will refer to locations within it.
Installing from Packages
The best way to install Dashboard is with Puppet Labs official package repositories. This willautomatically handle Dashboards dependencies, and will make for easier upgrades when newversions are released.
When installing from packages, Dashboard will be installed in /usr/share/puppet-dashboard , andthe puppet-dashboard user and group will own the files; this user will be automatically created if itdoesnt exist.
1. Install the operating system packages:
2. Install the RubyGems package system, using the following shell script do not use the rubygemspackaged with the operating system:
3. Create gem as an alternative name for the gem1.8 command:
Puppet Dashboard Manual Puppet Dashboard 1.2 Manual 4/27
ENABLING THE REPOSITORY
Before installing, follow the instructions here to enable the Puppet Labs package repository for yoursystem.INSTALLING DASHBOARD
On RPM-based systems, install Puppet Dashboard via Yum:
On Debian-based systems, install Puppet Dashboard via Apt:
Installing from Git
If youre unable to use the Dashboard packages on your system, the next best way to installDashboard is from the Puppet Labs Git repo. In the directory where you want Dashboard installed(we suggest /opt/ or /usr/share/ ), run:
The advantage of using Git is that you have an easier upgrade path: you dont have to manuallyremember which files to preserve when upgrading, and the actual process of upgrading is muchsimpler. The disadvantage is that it basically turns Git into another dependency. See upgrading formore details.
If you havent installed Dashboard from a package, you must create a user and group forDashboard and chown all its files to be owned by that user and group:
Installing from Source Tarballs
If you prefer not to use Git, you can simply download the most recent release of Puppet Dashboardand extract it into your install location:
Puppet Dashboard Manual Puppet Dashboard 1.2 Manual 5/27
If you havent installed Dashboard from a package, you must create a user and group forDashboard and chown all its files to be owned by that user and group.
Configuring DashboardDashboard needs a config/database.yml file and a config/settings.yml file. It ships withfunctional examples of each, as config/database.yml.example andconfig/settings.yml.example respectively.
The database settings file is located at config/database.yml , and an example file can be found atconfig/database.yml.example . This file should be a YAML hash with one key for each of thestandard Rails environments: production, development, and test.
The production environment gives the best performance, and should be used most of the timeby most users. Rails does not consider production its default environment, and you must specifyit manually with the RAILS_ENV environment variable when running any rake tasks or starting aWEBrick server.The development environment gives worse performance, but yields better logging and errorreporting when something goes wrong.The test environment is only used for running Dashboards automated tests, and should neverbe used by most users.
You will likely only ever be using the production environment. You may wish to use the samedatabase for the production and development environments, as this can remove the pain of havingto specify RAILS_ENV=production for every rake task and gives you the option of running atemporary instance with the same data in the development environment (if you ever need to collectdetailed error messages, for example). You should not use the same database for the testenvironment, as it gets destroyed every time the tests are run.
Each environment in the database.yml file should be a hash with keys for database , username ,password , encoding , and adapter . At the moment, adapter can only be mysql , and encodingshould always be utf8 .
Do not give Dashboard the keys to MySQLs root user account create a new database user for it(preferably named dashboard) and choose a secure password.
Since the database.yml file has to contain Dashboards database user and password in cleartext,you should set its mode to 660 (or some other world-unreadable mode). If youve created the filewhile logged in as a normal user, be sure to chown it to the Dashboard user.
Puppet Dashboard Manual Puppet Dashboard 1.2 Manual 6/27
The general settings file should be a YAML hash. When first configuring Dashboard, you shouldsimply make a copy of settings.yml.example , as its unlikely that youll need to change anysettings yet. (Although you may wish to change date_format , custom_logo_url , orno_longer_reporting_cutoff .)
Creating and Configuring a MySQL DatabaseDashboard needs a user, a password, and at least one database. Create these