Installation Documentationx - i4Life cross-mapping tools

brawnywinderSoftware and s/w Development

Dec 13, 2013 (3 years and 6 months ago)

78 views



Installation Documentation




















Installation Documentation





i4Life


Tomas Basham
, Andrew Jones

October 10
, 2012





Installation Documentation

Revision history


17 September 2012

Version 1

Tomas Basham

10 October 2012


Version 2

Revised by ACJ to incorporate minor

corrections

and explications

27 October 2012

Version 3

Minor corrections. Added MySQL user

descriptions and repository tag to
build.properties





Installation Documentation

Table of Contents

Installation Documentation

................................
................................
................................
..........................

1

Install Prerequisite Applications

................................
................................
................................
............................

4

Install Prerequisite Perl Modules

................................
................................
................................
...........................

4

Alter my.cnf to Allow Database Connections

................................
................................
................................
......

5

Alter php.ini to Allow Large Uploads

................................
................................
................................
.....................

5

Enable .htaccess

................................
................................
................................
................................
.............................

5

Acquire the Build Script and Properties Files

................................
................................
................................
....

6

Alter build.properties to Customise Installation Parameters

................................
................................
......

6

Run the Build Script

................................
................................
................................
................................
.....................

6






Installation Documentation

Install Prerequisite Applications


This document assumes that a flavor of Linux is installed, has a standard LAMP installation and
has
at
least on
e user
account for the

database with enough privileges

to create databases, tables and
triggers.


Before
installing the cross
-
mapping software
, several other a
pplications need to be present.
Although
the build scrip
t that accompanies the software

will attempt to
install these for you, if not already

present, it is recommended that they be ins
talled manually to avoid errors and complications. U
sing

the package manager that comes as part of most Linux distributions (Debian/Ubuntu assumed)
one
needs to install the fo
llowing:




php5
-
cli



mysql
-
client



libmysqlclient
-
dev



perl



make



gcc



unzip



subversion


An alternative to using a MySQL account which can create databases is to create a MySQL account
and grant it all rights over the database you are going to use. At the mysql
command line, as user root
(or similarly privileged user), create your new user:


CREATE USER 'myuser'@'localhost' IDENTIFIED BY 'mypassword';


Grant privileges on the database you will be using (which need not exist at this point):


GRANT ALL ON mydbname
.*

TO 'myuser'@'localhost';


Or the install script could be revised to operate on an already
-
created database, in which case the
user would not need database creation privileges …


Install Prerequisite Perl Modules


In addition to installing the above app
lications, several

P
erl modules
, not included in the standard
installation,

need to be present.

As before
,

the build scrip
t

will attempt to install these for you, if not
already

present, however it is recommended that they be installed manually to avoid er
rors and
complications.
As the root user

one needs to issue the following commands within the

cpan

application shell
.
It is important that you run cpan as root (sudo

will do). The first time you run it, it will
take you through some set
-
up activities; it is likely that you will be able to accept all the defaults
offered. Having completed the set
-
up activities:




install YAML



install IO::Interactive



install Archive::Zip



install DBI



install DBD::mysql



install Term::ReadKey



install
DateTime



install Try::Tiny



Installation Documentation


Then reboot, to be on the safe side.


Alter my.cnf to Allow Database Connections


On a standard installation of MySQL, for security reasons, the database will have been restricted to
allow connections to be made only from the host it is running on using only the loopback address
(127.0.0.1). For the software to run correctly this will n
ot be adequate and as such it is necessary to
remove this restriction. As the root user edit the file
/etc/mysql/my.cnf

to
ensure that the line
,


bind
-
address


is commented
out
.

This will allow both the Perl and PHP code to access the database using
the

lo
calhost syntax as opposed to being forced to use 127.0.0.1.


Database permissions


The database user needs certain permissions to
be able to create, modify and delete tables, as well
as the ability to write file to disk. This last ability is not always set

by default, and can be added with
the line :


GRANT FILE

ON *.* TO ‘yourUserName’
@'localhost';


This allows the cross
-
mapping output to be produced and stored for future downloading.


Alter php.ini to Allow
Large Uploads


Assuming that the web server being used
is Apache2

t
here are several settings in the php.ini file that
need to be changed in order for the server to accept large files being uploaded (such as the catalogue
of life).

If some other server

is in use, consult
the documentation for that particular application.

In the
php.ini file, typically found under /etc/php5/apache2/ search

for

and replace

each of the

following
setting

to

match the values below
:


upload_max_filesize


200M

post_max_size


200M

max_execution_ti
me


30

max_input_time


60

memory_limit



1000M


Once each of the above values has been changed save the file and restart
the A
pache
web server.


Enable .htaccess


Some of the files in the software are protected by a .htaccess

file to prevent leaking database
usernames and passwords to the average user. Again assuming Apache is being used, one needs to
alter the file /etc/apache2/sites
-
available/default. Find the section that looks like the following:


<Directory /var/www/>



Options Indexes FollowSymLinksMultiViews

AllowOverride None


Order allow,deny


Allow from all

</Directory>


and change “AllowOverride None” to “AllowOverride All” (ignoring the quotes).



Installation Documentation


Acquire the Build Script and Properties Files


In order to ins
tall the
cross
-
mapping
s
oftware, two files are required

that are responsible for
automatically fetching and placing the software files in their appropriate directories and also configures
the software to be used on a particular machine. These files can
fou
nd on the repository

and
are

named

build.sh and build.properties. To acquire

these run the following command
s

within a directory
you wish to download the

files:


svn

export <url to repository>/trunk/build.sh

svn

export <url to repository>/trunk/
build.properties


replacing<url to repository> for the URL describing the location of the

repository in which these files
are to be downloaded from
; for example,

svn+ssh://
biodiversity.cs.cf.ac.uk/usr/local
/svn
/repositories/i4Life” (minus the quotes).


Al
ter build.properties to Customise Installation Parameters


Lastly
, in terms of pre configuration,

one
needs to edit the build.properties file, supplying

the correct
configuration information.

The values

given
will be used by the build s
cript to configure t
he software,
replacing

placeholders

in the config.ini and import.tmconf files. It is very important to ensure that
before running the script, these values are updated and correspond to information already

pre
-
existing
prior to building the software
on the
host machine. For example supplying a username that does not
exists in the MySQL database will consequently mean that the database used by the software will not
be installed making the software inoperable.

The variables contained within the file are as

fol
lows:


VERSION

The major version number

REVISION

The minor or revision version number

WEBSERVER_BASE

The root directory used by the web server (e.g.
/var/www)

BASEURL

The root directory of the cross
-
mapping tools (e.g.
crossmapping)

PHP_DIR

The root
directory to install the PHP code (e.g.
/var/www/crossmapping)

PERL_DIR

The root directory to install the Perl code (This
path must also be one of the search paths of your
Perl installation e.g. /usr/local/lib/site_perl)

SMARTY_DIR

The root directory to
install the Smarty library

DBHOST

The host in which the database resides (e.g.
localhost)

USERNAME

The username required to access the database

PASSWORD

The password required to access the database

NAME

The name of the database to create and use

SVN_REPOSITORY

The svn location used to download the source
code. May require a username in the form
name@location/file/path. Also probably requires
svn:// or svn+ssh:// precursor.


Run the Build Script


As a final step, the build script must be run under

the root user using the following command:




Installation Documentation

./build.sh