Flux»Projects

RackMonkey 1.2.4 Generic Install Instructions

RackMonkey 1.2.4 Documentation Index

RackMonkey Version 1.2.4
©2004-2008 Will Green (wgreen at users.sourceforge.net)
Licensed under the GNU Public Licence v2.

Contents

  1. Introduction
  2. System Set Up
  3. Installing RackMonkey
  4. Configuring the Web Server
  5. Configuring RackMonkey
  6. Database Set Up
  7. Running RackMonkey

1. Introduction

This document explains how to install RackMonkey.

In future RackMonkey will be available in package form for common operating systems and include more OS specific installation instructions. For this release all installations should follow this document.

If you are upgrading an existing RackMonkey installation, please refer to upgrade.txt. This file is intended for new installations only.

Please note that the $ or # shown at the start of commands represents the shell prompt, you should not type it.

2. System Set Up

You need the following in order to install and use RackMonkey:

The easiest way to install modules is with the CPAN shell. You generally need to be root in order to do this. 

# perl -eshell -MCPAN

On Mac OS X you can use sudo to temporarily become root (enter your usual password when prompted): 

$ sudo perl -eshell -MCPAN

Once the shell has started (you may be prompted to configure it): 

install DBI
install CGI
install HTML::Template

Then install the database driver for the database you're using:

3. Installing RackMonkey

Once you have obtained a copy of RackMonkey (see README) you should have a directory with the following layout:

Copy the rackmonkey.pl file and the whole RackMonkey directory from the perl directory to a suitable location on your web server (e.g. /rackmonkey) and ensure that rackmonkey.pl is executable by the web server user.

NB. Do not install RackMonkey in a path containing spaces as this will cause difficulties with configuration and lead to ugly URLs with %20 in them.

For example, to make rackmonkey.pl executable by all users run:

$ chmod 755 rackmonkey.pl

The RackMonkey script uses /usr/bin/env to choose the perl revision to run. If you want to specify a specific version of perl, or your env command lives in another directory, you need to update the #! line at the top of rackmonkey.pl.

Copy the tmpl directory to somewhere that can be read by the web server, but ideally not in web space, for example: /home/rackmonkey/tmpl

Copy the contents of the www directory to somewhere within web space where you want to serve web content from, e.g. /rackmonkey within the web root. This directory needs to be accessible from a web browser. If you choose to serve RackMonkey from another location you will need to update httpd-rackmonkey.conf to reflect this in section 3 (below).

4. Configuring the Web Server

RackMonkey includes an Apache configuration snippet that allows you to enable the right settings for http://<yourserver>/rackmonkey. If you are happy to serve RackMonkey from this location then you can simply include conf/httpd-rackmonkey.conf in your Apache configuration. For other web servers you may need to consult your server documentation on running CGI applications.

Linux

On most Linux distros you can configure Apache by copying conf/httpd-rackmonkey.conf into /etc/apache2/conf.d and getting Apache to reread its configuration.

On Debian and Ubuntu:

# /etc/init.d/apache2 force-reload

On Red Hat based Linux systems (including CentOS and RHEL):

# service httpd reload

Mac OS X 10.5 (Leopard)

Open a terminal and become root with: 

$ sudo bash

Copy conf/httpd-rackmonkey.conf into /private/etc/apache2/other/ and reload apache configuration with: 

# apachectl graceful

NetBSD

Copy conf/httpd-rackmonkey.conf into /usr/local/etc/apache and add the following line to the bottom of /usr/local/etc/apache/httpd.conf 

Include /usr/local/etc/apache/httpd-rackmonkey.conf

Then reload apache configuration with:

# /etc/rc.d/apache reload

Other Operating Systems

Copy conf/httpd-rackmonkey.conf into your Apache configuration directory, which is often found in /etc/ or /usr/local/etc and is generally called httpd, apache or apache2. Then add the following line to your httpd.conf: 

Include /<path>/httpd-rackmonkey.conf

Replacing <path> with wherever you put httpd-rackmonkey.conf.

You can then get apache to reload its configuration using: 

# apachectl graceful

Or, if you don't have apachectrl available, by sending using kill -HUP on the apache parent process.

If you're having difficulty locating Apache configuration information you may find http://wiki.apache.org/httpd/DistrosDefaultLayout helpful.

5. Configuring RackMonkey

Configuration Overview

This release of RackMonkey (v1.2.4) uses a different configuration format from past releases. Configuration is now stored in a text file, which is read from /etc/rackmonkey.conf by default. If you're happy with this location, simply copy conf/rackmonkey.conf-default to /etc/rackmonkey.conf and proceed to the configuration editing section (below).

NB. If you use Postgres or MySQL this configuration file will contain your RackMonkey database username and password. For maximum security I recommend only root (or the RackMonkey admin) and the web server can read this file.

Changing Configuration Path

If you want to place the configuration in another location you need to tell RackMonkey where to find it using an environment variable. To do this for Apache, edit the SetEnv RACKMONKEY_CONF line in httpd-rackmonkey.conf (which you installed above) to point at your chosen path.

Editing Configuration

Before you can run RackMonkey you need to edit the configuration file to match your directory and database locations.

Comments in the configuration file are included with the a #. Comments must either start a line or be preceded by whitespace. Values in the configuration file cannot include spaces and configuration variables are lower case:

tmplpath sets the filesystem path to your template files, it should be an absolute path and match where you put the files during installation (see section 2, above), something like: 

tmplpath = /home/rackmonkey/tmpl

wwwpath sets the path within web space that your web content resides (that is relative to the DocumentRoot in Apache), for example: 

wwwpath = /rackmonkey/www

You now need to configure RackMonkey to connect to your database.

For SQLite

When using SQLite you need to choose a filesystem path for your database, for example if you want your database to reside in /home/rack/rackmonkey.db, use: 

dbconnect = dbi:SQLite:dbname=/home/rack/rackmonkey.db

NB. This path must be writable by the web server and should not be within web space, or users will be able to download your database. As we're using SQLite you can leave the DBUSER and DBPASS values blank. Make sure the 'SQLite' in the dbconnect string is in the case shown.

For Postgres

You will create a Postgres database and user in section 5. For now choose a database name, username and password. For simplicity I recommend you make the database and username both 'rackmonkey'. An example configuration would be: 

dbconnect = dbi:Pg:dbname=rackmonkey
dbuser = rackmonkey
dbpass = 7jhH#98*

NB. Make sure the 'Pg' in the dbconnect string is in the case shown.

If your database is on a remote server you need to add the hostname of the database server. For example, if your database server is db1.example.com: 

dbconnect = dbi:Pg:dbname=rackmonkey;host=db1.example.com

If your database server is not using the standard Postgres port (5432) you should also indicate this in the connection string. For example, if your database is on db1.example.com port 9000: 

dbconnect = dbi:Pg:dbname=rackmonkey;host=db1.example.com;port=9000

You can also connect to a local database on another port:

dbconnect = dbi:Pg:dbname=rackmonkey;port=9000
For MySQL

NB. MySQL support is still experimental. It will be fully supported in v1.2.5. RackMonkey requires features only available in MySQL 5 or higher, v3 or v4 will not work.

You will create a MySQL database and user in section 5. For now choose a database name, username and password. For simplicity I recommend you make the database and username both 'rackmonkey'. An example configuration would be: 

dbconnect = dbi:mysql:dbname=rackmonkey
dbuser = rackmonkey
dbpass = 7jhH#98*

NB. Make sure the 'mysql' in the dbconnect string is all lowercase.

If your database is on a remote server you need to add the hostname of the database server. For example, if your database server is db1.example.com: 

dbconnect = dbi:mysql:dbname=rackmonkey;host=db1.example.com

If your database server is not using the standard MySQL port (3306) you should also indicate this in the connection string. For example, if your database is on db1.example.com port 9000: 

dbconnect = dbi:mysql:dbname=rackmonkey;host=db1.example.com;port=9000

You can also connect to a local database on another port: 

dbconnect = dbi:mysql:dbname=rackmonkey;port=9000

6. Database Set Up

Before you can run RackMonkey you need to set up the database. You must run the schema and default_data SQL files against the database or else it won't work. Once they have run you can optionally install the sample data.

For SQLite

Make a note of the path you specified for DBDCONNECT, then run both of the following to set up the database and install the default data (required): 

$ sqlite3 [PATH] < sql/schema.sqlite.sql
$ sqlite3 [PATH] < sql/default_data.sql

You should also install the optional sample data if you want common companies and operating systems etc. set up in RackMonkey (this will save you a lot of work entering data and you can always delete the ones you don't want): 

$ sqlite3 [PATH] < sql/sample_data.sql

You should then change the permissions of the database file [PATH] and its parent directory to be readable and writable by your web server. For example, you might change the owner to 'www' if that is the user your web server runs under.

For further information on administering SQLite see: http://www.sqlite.org/docs.html.

For Postgres

Using the values you set in section 4 you can create your RackMonkey user and database. Assuming you called both your user and database 'rackmonkey' you run (entering your chosen password when prompted): 

# su - postgres
$ createuser --pwprompt
Enter name of role to add: rackmonkey
Enter password for new role: 
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n
CREATE ROLE

$ createdb -O rackmonkey rackmonkey
CREATE DATABASE

Run both of the following to set up the database and install the default data (assumes your database is called rackmonkey): 

$ psql -U rackmonkey rackmonkey < sql/schema.postgres.sql
$ psql -U rackmonkey rackmonkey < sql/default_data.sql

You should also install the optional sample data if you want common companies and operating systems etc. set up in RackMonkey (this will save you a lot of work entering data and you can always delete the ones you don't want): 

$ psql -U rackmonkey rackmonkey < sql/sample_data.sql

For further information on administering Postgres see: http://www.postgresql.org/docs/.

For MySQL

Connect to your MySQL instance as a user with admin powers. Then create the rackmonkey database and connect to it: 

mysql> create database rackmonkey;
mysql> use rackmonkey;

Next, import the RackMonkey schema and default data (required): 

mysql> \. sql/schema.mysql.sql
mysql> \. sql/default_data.sql

Check all queries were OK in the output from the schema import. You can check all 19 tables were imported: 

mysql> show tables;
...
19 rows in set (0.00 sec)

You should also install the optional sample data if you want common companies and operating systems etc. set up in RackMonkey (this will save you a lot of work entering data and you can always delete the ones you don't want): 

mysql> \. sql/sample_data.sql

Finally you need to create a user and password to match your configuration file (in section 4, above). For local connections: 

mysql> GRANT ALL ON rackmonkey.* TO 'rackmonkey'@'localhost' IDENTIFIED BY '7jhH#98*';

To also allow connections from other servers run: 

mysql> GRANT ALL ON rackmonkey.* TO 'rackmonkey'@'%' IDENTIFIED BY '7jhH#98*';

You should then flush privileges to ensure all connections see them:

mysql> FLUSH PRIVILEGES;

For further information on administering MySQL see: http://dev.mysql.com/doc/.

7. Running RackMonkey

You can now start the app by pointing your browser at the location of the rackmonkey.pl script. You should be presented with a screen showing a list of racks. If everything works correctly you probably want to start reading the User Guide, which you can find under the [Help] tab in the RackMonkey interface. If you're having trouble getting RackMonkey to run (for example you get an Internal Server Error), read troubleshooting.txt.

RackMonkey 1.2.4 Documentation Index