INSTALLING HELIOS

Installing Helios isn't terribly hard itself, but it does require 
several prerequisites.  This file details the necessary steps that should work 
for several operating systems.  Check this distribution to see if there is 
another INSTALL.* file for your specific operating system.

The general steps involve:
* Install MySQL & helios_db Database Schema
* Configure helios.ini file
* Install Helios & dependencies
* Install Apache or other web server (optional; only to submit jobs via HTTP)

In general, you should probably install your MySQL database, then install 
Helios and its prerequisites on one server, and then install Apache and the 
job submission CGI if you want to submit jobs via HTTP.  Once you have Helios 
running on one host, installing and running Helios on other hosts will be 
easier.


GENERIC INSTRUCTIONS

The following instructions should work to install Helios on most Unix-style 
platforms.  If your platform has some of these things prepackaged (MySQL and
Apache, hopefully), you can save yourself some time by using the prepackaged 
versions.


1) Install MySQL & helios_db Database Schema

You'll need to install MySQL and create a database and a user that all the 
Helios hosts can log into.  Once you have MySQL up and running, you can use 
the sql/helios_schema.sql file to create the Helios database schema.  Open the 
file in a text editor, uncomment the lines that create the helios db user, and 
edit them as appropriate for your security situation.  Then use the following 
line to create the helios_db database:

    mysql -u root -p < sql/helios_schema.sql

You'll be prompted for the MySQL root user's password, then the helios_db 
database will be created with helios database user and all the tables 
necessary for the Helios system.


2) Configure helios.ini

Just about everything in Helios depends on a helios.ini file to specify 
initial settings and connection information for the Helios database.  The 
helios.pl service loader/daemon will look for its .ini file in 
the location specified by the HELIOS_INI environment variable, so adding 

    export HELIOS_INI=/path/to/helios.ini

to either your global user profile or the profile of the user you intend to run     
Helios under is probably a good idea.  

There is a sample helios.ini file included in the Helios distribution to help 
guide your initial install.  To specify the Helios database connection, specify 
the correct dsn, user, and password values in the [global] section.  Helios by 
default will place PID files for the daemons it launches in "/var/run/helios"; 
you may want to change this location by specifying the pid_path parameter.  
There are other parameters you can specify; check the helios.pl man page for 
more information. 


3) Install Helios & CPAN dependencies

Helios requires the following modules to be installed:

    DBI
    DBD::mysql
    XML::Simple
    Data::ObjectDriver
    TheSchwartz
    Config::IniFiles
    Error
    Pod::Usage

You can download and install these packages manually, or you can use the 
CPAN shell.  As your root user or via sudo, issue the following commands to 
install Helios and its dependencies:

	perl -MCPAN -eshell
	install Data::ObjectDriver
	install TheSchwartz
	install Error
	install Test::Simple
	install Pod::Usage
	install Config::IniFiles
	install Helios

You may also try the Helios generic CPAN bundle.  It may not work in all 
cases on all systems, but it may save you some time:

	perl -MCPAN -eshell
	install Bundle::Helios::Generic

If the HELIOS_INI environment variable is set, make test will 
attempt to use the information in the .ini file to connect to the specified 
Helios database and read configuration parameters from it.  If HELIOS_INI isn't 
set, that test will be skipped.
 
 
4) Final checks 

At this point, your Helios host should be ready to service jobs.  If you want 
to do further tests, you can use Helios::TestService.  Helios::TestService 
runs in your Helios collective like any other service, but it only records the 
job arguments passed to it in the Helios log.  Once you're satisfied your 
Helios host is configured properly, you can move on to installing Helios on the 
next host in your collective.


5) Install Apache & jobSubmit.pl CGI (optional)

Install Apache on the host(s) you want to send HTTP to submit jobs.  This 
server(s) will need to have the same database access as the other Helios 
hosts, regardless of whether it will be running jobs.  It's probably best to 
simply use your first host for this, at least until your get the rest of your
Helios collective up and running.  Make sure Apache is configured to run CGI 
programs.

You could also use another HTTP server with CGI capabilities.  There's no 
reason it shouldn't work, but Helios hasn't been tested with other web servers, 
so YMMV.

If you don't want to submit jobs via HTTP, you don't have to install Apache, 
though the Helios::Panoptes admin interface (packaged separately) will still 
need it.

Once the Helios base libraries are installed, you can optionally install the 
job submission CGI in your host's cgi-bin directory to support job submission 
via HTTP.  If your cgi-bin directory is, say, /usr/local/apache/cgi-bin:

    cp cgi-bin/submitJob.pl /usr/local/apache/cgi-bin/
 	chown root.root /usr/local/apache/cgi-bin/submitJob.pl
	chmod a+rx /usr/local/apache/cgi-bin/submitJob.pl
    
should put submitJob.pl in the right place and set the proper ownership and 
permissions.