search

Aethylred / puppet-puppetdashboard

This Puppet module manages the installation of the Puppet Dashboard web interface.
2 stars 2 forks source link

readme

Puppet Dashboard Module

Build Status

This is a Puppet module to manage the Puppet Dashboard that is compatible with the Puppetlabs Apache Module and the NeSI Puppet Module.

Introduction

The purpose of this module is to install the Puppet Dashboard using the Puppetlabs Apache Module, but without explicitly installing or configuring any other services or resources. This separation of concerns should allow the Puppet Dashboard to be installed independently of puppet and puppet-master services and should allow the Puppet Dashboard to not interfere with the web server and database if they are used by other applications or services.

Installation

The following Puppet snippet will do a default install of the Puppet Dashboard as the default site on port 80:

class{'ruby':
    version         => '1.8.7',
    latest_release  => true,
  }
class { 'ruby::dev': }
class {'mysql::server':
  override_options => {
    'mysqld' => {
      'max_allowed_packet' => '32M',
    }
  }
}
class {'mysql::bindings':
  ruby_enable               => true,
  ruby_package_ensure       => 'latest',
  client_dev                => true,
  client_dev_package_ensure => 'latest',
}
class {'apache':
  default_vhost => false,
}
class { 'apache::mod::passenger':
  passenger_high_performance => 'on',
  passenger_max_pool_size => 12,
  passenger_pool_idle_time => 1500,
  passenger_stat_throttle_rate => 120,
  rails_autodetect => 'on',
}
class { 'puppetdashboard':
  require => Class['apache::mod::passenger'],
}

Dependencies

The Puppet-Dashboard Module has been written such that its component classes can be installed on different servers. Hence the dependencies are not across all classes and allows the installation of the database on a database server without a web service, while the web application can be installed on a web server with without a database service. The current version of the Puppet Dashboard does not yet support a remote database.

The included PuppetFile can be used with librarian-puppet to set up the module dependencies.

In all cases, these modules should be installed and be available on the Puppet Master, though not necessarily installed on each host using classes and resources from the Puppet-Dashboard Module.

Required Puppet Module Dependencies

Optional Puppet Module Dependencies

These modules can make using the puppetdashboard module easier, and some are required for the git provider (check the git provider documentation for details) :

Apache Web Server Configuration

This module requires that the Apache web server is installed and configured to run with Passenger. The following Puppet snippet is the recommended minimal configuration for Apache running the Puppet Dashboard that produces a virtual host configuration that matches the Puppet Dashboard documentation:

class {'apache':
  default_vhost => false,
}
class { 'apache::mod::passenger':
  passenger_high_performance => 'on',
  passenger_max_pool_size => 12,
  passenger_pool_idle_time => 1500,
  passenger_stat_throttle_rate => 120,
  rails_autodetect => 'on',
}

MySQL Database Server Configuration

This module does not require the MySQL server to be running or configured locally.

This module does not install or manage the MySQL server. This is in order to maintain isolation of the MySQL service and the Dashboard application so that the Puppet Dashboard does not interfere with the installation and configuration of a MySQL server. Puppet Dashboard requires that the MySQL server is configured to allow large (at least 32MB) packet sizes using the max_allowed_packet setting. A minimal MySQL server configuration using the Puppetlabs Mysql Module is given below:

class {'mysql::server':
  override_options => {
    'mysqld' => {
      'max_allowed_packet' => '32M',
    }
  }
}
class {'mysql::bindings':
  ruby_enable               => true,
  ruby_package_ensure       => 'latest',
  client_dev                => true,
  client_dev_package_ensure => 'latest',
}

PostgreSQL Database Server Configuration

This module does not require the PostgreSQL server to be running or configured locally.

This module does not install or manage the PostgreSQL server. This is in order to maintain isolation of the PostgreSQL service and the Dashboard application so that the Puppet Dashboard does not interfere with the installation and configuration of a PostgreSQL server.

Using the Puppetlabs PostgreSQL Module the following puppet snippet will set up a local PostgreSQL for the Puppet Dashboard:

class {'postgresql::server':
  listen_addresses => 'localhost',
}
class {'postgresql::lib::devel':
  link_pg_config => false,
}

Classes and Resources

The base class can be used to manage all the other classes provided by this module. It does provide the option to not manage some classes so that those classes can be instanced separately, or the resources that they manage can be defined independently.

The parameters are described in the base class and the default values given are the same in the other classes. As the parameter names are consistent across classes the other classes will simply list the parameters they can use.

Some classes have been created as sub-classes to simplify the addition of future classes to support alternative services (e.g. PosgreSQL or Ngnix) or operating systems (e.g. RedHat). For example, the database class has been created as puppetdashboard::db::mysql to allow for the future creation of a puppetdashboard::db::posgres class.

The base puppetdashboard class

The puppetdashboard::config class

The puppetdashboard::db class

The puppetdashboard::db::mysql class

The puppetdashboard::db::postgresql class

The puppetdashboard::db::postgresql class

The puppetdashboard::install::git class

The puppetdashboard::install::package class

The puppetdashboard::site::apache class

The puppetdashboard::site::webrick class

The puppetdashboard::workers::debian class

Other Features

Git Provider

The git provisioner installs the puppet-dashboard from the Puppet Dashboad git repository on GitHub. This allows the dashboard installation from unpackaged versions and onto Linux distributions that do not have packages available to them. Using the git provisioner requires the git package to be installed, and that the Puppetlabs vcsrepo module is installed.

The git provider requires that:

A working manifest that can do this is given in tests/git_install.pp, a Puppetfile for librarian-puppet is provided that will install the dependent Puppet Modules required to make this work. The script and Puppetfile have been tested on Ubuntu 12.04 LTS.

Currently the git provider requires 3 puppet runs to complete the install. There is some issues with specifying the ordering of the install of a PPA repository, installing packages, and executing commands than need resolving.

It is recommended that the git provisioner is used as it is not dependent on end-of-life versions of Ruby, and can install the latest version of the Dashboard. It currently works for the Puppet Dashboard version 2.0.0-beta2.

PosgreSQL database

The Puppet Dashboard application supports the use of a PostgreSQL database. This is only supported with the later versions that can be installed with the git provider, hence has the same dependencies and configuration requirements.

A working manifest that can do this is given in tests/postgres_git.pp, a Puppetfile for librarian-puppet is provided that will install the dependent Puppet Modules required to make this work. The script and Puppetfile have been tested on Ubuntu 12.04 LTS. Note that this is still dependant on some MySQL development libraries being installed by the Puppetlabs MySQL module.

Managing Puppet Dashboard on webrick

This module can be used to set up the Puppet Dashboard on webrick, though this is not recommended and not well tested. Use the following Puppet snippet:

class {'mysql::server':
  override_options => {
    'mysqld' => {
      'max_allowed_packet' => '32M',
    }
  }
}
class {'mysql::bindings':
  ruby_enable               => true,
  ruby_package_ensure       => 'latest',
  client_dev                => true,
  client_dev_package_ensure => 'latest',
}
class { 'puppetdashboard':
  manage_vhost    => false,
  disable_webrick => false,
}

Troubleshooting

Make sure the installed Ruby, Ruby development libraries, and Rubygems are all compatible. Using a module to manage Ruby is recommended.

To Do

Acknowledgements

puppet-blank

This module is derived from the puppet-blank module by Aaron Hicks (aethylred@gmail.com)

This module has been developed for the use with Open Source Puppet (Apache 2.0 license) for automating server & service deployment.

Gnu General Public License

GPL3

This file is part of the puppetdashboard Puppet module.

The puppetdashboard Puppet module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The puppetdashboard Puppet module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the puppetdashboard Puppet module. If not, see http://www.gnu.org/licenses/.