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 Helios database schema
* Install expat2.
* Configure helios.ini file.
* Install Helios & dependencies.
* Install Apache or other web server & submitJob.pl script. (optional)

In general, once you have installed your database software and schema, you 
should then install Helios and its prerequisites on one server.  Once you have 
Helios running on one host, installing and running it on other hosts will be 
easier.  Plus, if you are running in a virtualized environment, you will then 
have the option of simply cloning your working Helios VM to add new machines 
rather than install everything from scratch repeatedly.


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,
Apache, and expat2, 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 your MySQL server and clients 
installed and running, you can use the sql/helios_schema_mysql.sql file to 
create the Helios database schema.  Open the file in a text editor, edit the 
lines that create the helios db user for your security situation.  Then issue 
the following command to create the helios_db database:

    mysql -u root -p < sql/helios_schema_mysql.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.

-- OR --

1) Install Oracle & Helios Database Schema.

If you are using Oracle for your Helios collective database you will need to 
install and configure Oracle on a server and install Oracle Instant Client, 
DBI, and DBD::Oracle on the system(s) you want to want to use as Helios worker 
hosts.  Make sure you can use sqlplus and DBD::Oracle to connect to your 
database before proceeding.

Once your Oracle client and DBD::Oracle client software is properly installed 
and configured, adapt the sql/helios_schema_oracle.sql to fit your Oracle 
environment.  You will need to create a database user for the Helios hosts to 
use to connect to the database, and (again, depending on your environment) you 
may need to create a tablespace as well.  Once the schema DDL is appropriately 
adapted to your environment, use sqlplus, SQL Developer, or another SQL tool 
to create the Helios database structures.


2) Install Expat2 development libraries.

The XML parser Helios relies on most often requires the Expat2 XML parsing 
library, but unfortunately the Perl CPAN client is unable to install this 
for you.  Most often this library will already be packaged for your operating 
system, either as a package or a separate downloadable binary.  In fact, you 
may already have it installed.  Check with your operating system documentation 
or the Expat website (http://expat.sourceforge.net/) for more information on 
installing it on your platform.  If you are using a pre-packaged version, make 
sure you install the development library package (often packaged with a -dev or 
-devel suffix) as well as the core package.

If you have trouble later in the installation when installing XML::Simple or 
one of its dependencies via the CPAN shell, it is probably because Expat is not
installed or is in a location your Perl interpreter cannot find.


3) 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 as 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. 


4) 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
    Test::Simple

You can download and install these packages manually, or you can use the 
CPAN shell (the preferred method).  To 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 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

If the HELIOS_INI environment variable is set, the Helios 'make test' install 
phase 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.
 
 
5) Final Checks of the Base Helios System. 

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.


6) Install Apache & submitJob.pl CGI (optional)

Install Apache on the host(s) you want to send HTTP to submit jobs.  The 
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.

    
# CHANGE HISTORY
# 2012-01-04: Split out Ubuntu instructions into separate INSTALL.ubuntu file.
# Updated both new files for the most recent releases of the OSes.  Clarified
# generic instructions in places.
# 2012-01-08: Split out Red Hat instructions into separate INSTALL.redhat file.
# Further updates to generic INSTALL instructions to streamline installation
# procedures.
# 2012-01-22: Added instructions for using Bundle::Helios::Generic to install 
# prerequisites.  Added extra instructions for installing submitJob.pl with
# correct ownership and permissions.
# [LH] [2012-11-06]: Explicitly mention expat2 library as a requirement, as it 
# is required for XML parsing but is not always installed with the base OS.
# Changed mentions of helios_schema.sql to helios_schema_mysql.  Added 
# instructions for Oracle database.  Added Test::Simple to the list of required 
# modules.  Changed mentions of Bundle::Helios::Generic to Bundle::Helios.  
# Minor other changes for clarity and grammar.