Preparation steps for Linux

Due to the large variety of Linux platforms, we tried to provide steps that should work on most distributions.
Help will be provided on the first day of the workshop if you encounter difficulties.

Prepare

Open a new shell.

A "working directory" will be used to install the software and to work during the workshop.

A good choice is to create a directory in your home directory:

mkdir ~/eurovodca/

Download all software installation files to this directory.

Note: the values in uppercase between curly brackets must be replaced by your own values.
For example, replace all {YOUR_PASSWORD} occurrences by an actual password of your choosing.
For my user account, the value of {YOUR_WORKING_DIR} is: /home/brino/eurovodca/

Download

A copy of the download files are available at http://www.euro-vo.org/dcaworkshop2008/CommonSoftware/Linux/

You are however advised to get the files from their original source. This will allow you to revise any applicable End User Agreements and software licenses before installing, and to know where to get updated versions of the software in the future.

Java JDK 1.5

Download

Go to your working directory:

cd ~/eurovodca/

Open the following URL: http://java.sun.com/javase/downloads/index_jdk5.jsp and click on the "Download" button next to "JDK 5.0 Update 15". Download the "Linux", "Multi-language", "Offline Installation" installation file (jdk-1_5_0_15-linux-i586.bin).

Or, to get the installation from the workshop copy site:

wget 'http://www.euro-vo.org/dcaworkshop2008/CommonSoftware/Linux/Java/jdk-1_5_0_15-linux-i586.bin'

Install

Execute the installation program:

sh jdk-1_5_0_15-linux-i586.bin

Configure

You now need to set the following environment variables:

JAVA_HOME=~/eurovodca/jdk1.5.0_15

And add java to your PATH:

PATH=~/eurovodca/jdk1.5.0_15/bin

Tomcat 5.5

Download

Go to your working directory:

cd ~/eurovodca

Open the following URL: http://tomcat.apache.org/download-55.cgi#Binary%20Distributions and download the "tar.gz" installation file.

Or, to get the installation from the workshop copy site:

wget 'http://www.euro-vo.org/dcaworkshop2008/CommonSoftware/Linux/Tomcat/apache-tomcat-5.5.26.tar.gz'

Install

Unpack the Tomcat package :

tar zxvf apache-tomcat-5.5.26.tar.gz

Create a link to this newly installed software for easy access :

ln -s apache-tomcat-5.5.26 tomcat

Configure

You now need to set the following environment variables:

CATALINA_HOME=~/eurovodca/tomcat
CATALINA_BASE=~/eurovodca/tomcat

Edit the user configuration file :

cd tomcat
vim conf/tomcat-users.xml

You should change the file from this :

<!--
  NOTE:  By default, no user is included in the "manager" role required
  to operate the "/manager" web application.  If you wish to use this app,
  you must define such a user - the username and password are arbitrary.
-->
<tomcat-users>
  <user name="tomcat" password="tomcat" roles="tomcat" />
  <user name="role1"  password="tomcat" roles="role1"  />
  <user name="both"   password="tomcat" roles="tomcat,role1" />
</tomcat-users>

To this :

<!--
  NOTE:  By default, no user is included in the "manager" role required
  to operate the "/manager" web application.  If you wish to use this app,
  you must define such a user - the username and password are arbitrary.
  recommended password: admin
-->
<tomcat-users>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user name="admin" password="{YOUR_PASSWORD}" roles="admin,manager" />
</tomcat-users>

(For testing purposes, a common value for this password is "admin")

Now, try to start your Tomcat server :

./bin/startup.sh

You should get :

Using CATALINA_BASE:   ~/eurovodca/tomcat
Using CATALINA_HOME:   ~/eurovodca/tomcat
Using CATALINA_TMPDIR: ~/eurovodca/tomcat/temp
Using JRE_HOME:       ~/eurovodca/jdk1.5.0_15

And shutdown your Tomcat server :

./bin/shutdown.sh

You should get :

Using CATALINA_BASE:   ~/eurovodca/tomcat
Using CATALINA_HOME:   ~/eurovodca/tomcat
Using CATALINA_TMPDIR: ~/eurovodca/tomcat/temp
Using JRE_HOME:       ~/eurovodca/jdk1.5.0_15

Finally, go back to your working directory:

cd ..

MySQL 5.0

Download

Open the following URL: http://dev.mysql.com/downloads/mysql/5.0.html#linux and download the installation file where "standard" is static.

Or, to get the installation from the workshop copy site:

wget 'http://www.euro-vo.org/dcaworkshop2008/CommonSoftware/Linux/MySQL/mysql-5.0.51a-linux-i686.tar.gz'

Install

tar zxvf mysql-5.0.51a-linux-i686.tar.gz
ln -s mysql-5.0.51a-linux-i686 mysql

Configure

You now need to set the following environment variables:

MYSQL_HOME=~/eurovodca/mysql

And add MySQL to your PATH:

PATH=~/eurovodca/mysql/bin

Execute the "configure" script provided :

cd mysql
./configure

By default the "root" user was given an empty password, that you might set ("root" is a common choice for testing purposes):

mysqladmin -u root password {YOUR_PASSWORD}

Note: recommended password: root

In the end, shut down your MySQL server :

./bin/mysqladmin shutdown -u root -p
(type in your password)

Finally, go back to your working directory :

cd ..

Ant

Download

Go to your working directory:

cd ~/eurovodca

Open the following URL: http://ant.apache.org/bindownload.cgi#Current%20Release%20of%20Ant and download the "tar.gz" installation file (apache-ant-1.7.0-bin.tar.gz).

Or, to get the installation from the workshop copy site:

wget 'http://www.euro-vo.org/dcaworkshop2008/CommonSoftware/Linux/Ant/apache-ant-1.7.0-bin.tar.gz'

Install

Unpack the ant package :

tar zxvf apache-ant-1.7.0-bin.tar.gz

Create a link to this newly installed software for easy access :

ln -s apache-ant-1.7.0 ant

Configure

You now need to set the following environment variables:

 ANT_HOME=~/eurovodca/ant

And add Ant to your PATH:

PATH=~/eurovodca/ant/bin

Perl 5 (optional)

Install

You shouldn't need to install Perl on Linux as it is already on your system.

To check this, type:

perl -v

You should get:

$ perl -v
This is perl, v5.8.8 built ...

PostgreSQL (optional)

Note: root access is required. When issuing a sudo command, you will be prompted for your root password.

Download

Go to your working directory:

cd ~/eurovodca

Open the following URL: http://www.postgresql.org/ftp/ and download the "v8.3.1", "postgresql-8.3.1.tar.gz" installation file.

Or, to get the installation from the workshop copy site:

wget 'http://www.euro-vo.org/dcaworkshop2008/CommonSoftware/Linux/PostgreSQL/postgresql-8.3.1.tar.gz'

Install

Add a postgres user in your system:

sudo adduser postgres
(type in your password)

Note: recommended password: postgres

Unpack the postgresql package:

tar zxvf postgresql-8.3.1.tar.gz

Create a link to this newly installed software for easy access :

ln -s postgresql-8.3.1 postgresql

Create the pgsql directory:

mkdir pgsql

Compile and install postgresql:

cd postgresql
./configure --prefix=<your home directory>/eurovodca/pgsql
make
make install

Change directory owner for pgsql

sudo chown -R postgres:postgres pgsql
(type in your password)

Use the postgres user:

su postgres -

set the environment variable for postgres user:

MANPATH=~/eurovodca/pgsql/man
PGLIB=~/eurovodca/pgsql/lib
PGDATA=~/eurovodca/pgsql/data

And add PostgreSQL to your PATH:

PATH=~/eurovodca/pgsql/bin

Initialize the database:

initdb

Configure

Start the database server:

pg_ctl start

Shutdown the database server:

pg_ctl stop

Test the installation

Once you have installed and configured all the required software, you should run the test script.

This test script verifies that you have (details below):

• installed all required software
• server software (Tomcat, MySQL, PostgreSQL) are running
• made the necessary configurations
• set the environment variables as described

If all is well, you will be greeted with a success message; if not, with an error message. Additional software used only in some sessions (Perl, PostgreSQL) is also tested for; warning (instead of errors) are issued in case.

Steps

1. Download
2. Unpack
3. Configure
4. Run

Download

• • Windows: testsetup.zip
  • Linux or MacOSX: testsetup.tar.gz

Configure

You must edit the properties file test.properties to reflect some of your installation settings. If you followed the installation instructions most notably the usernames and passwords, there should be no need to edit this file.

If you already had some of the software installed and want to use it, make the appropriate changes to this file and you will be able to test all your environment is setup correctly. This also allows to verify that a computer other than your laptop can run the software required for the workshop.

Run

Before running the test script, the following installed server software must be running: Tomcat, MySQL, PostgreSQL

To run the test script, just execute on a command line (make sure the current directory is the "testsetup" directory):

• on Windows: test.bat
• on Linux and MacOSX: ./test.sh

Note: Java is required to run the test script.

What is tested:

Java JDK

• Version is 1.5
• JAVA_HOME environment variable set
• JAVA_HOME/bin is on the PATH

Ant

• Version is 1.6+
• ANT_HOME environment variable set
• ANT_HOME/bin is on the PATH

Tomcat

• Version is 5.5
• Running at http://localhost:8080
• Running under Java 1.5
• CATALINA_HOME and CATALINA_BASE environment variables set
• write permissions to CATALINA_BASE/webapps
• user admin/admin has "manager" role

MySQL

• Version is 5.0
• MYSQL_HOME environment variable set
• MYSQL_HOME/bin is on the PATH
• user root/root has can create databases

Perl 5 (optional)

• Version is 5

PostgreSQL (optional)

• user postgres/postgres can create databases

Known issues and troubleshooting:

• The first time the test script is run, a series of messages stating *sys-package-mgr*: processing new jar are displayed. These can be safely ignored.
• An error message appears sporadically stating Write end dead. Please re-run the test script, as it should disappear.
• If the first error message is Testing Java...  Failed to get environment, environ will be empty, you might be using a custom version of Java that is not adequate. Please download and install the Java JDK from Sun as described in the instructions.

About environment variables

Environment variables are system-wide settings that configure your computer. They are used, among other things, to make sure that several programs on your system are easy to find.

To set an environment variable in Linux:

• Open a new shell session
• Check what is your shell by typing echo $SHELL
  • if it is /bin/bash
    • configuration file is: ~/.bash_profile
    • syntax is: export VAR_NAME=value
  • if it is /bin/tcsh
    • configuration file is: ~/.tcshrc
    • syntax is: setenv VAR_NAME value
• Edit the configuration file to add the export/setenv statements, one by line. Take care to identify variables that already exist, and update them properly.
• The changes made to the configuration file are valid once you save the file, but they will only be visible in Terminal sessions started after the changes.
• To apply the changes to an existing Terminal session, execute the following command:
  • bash: source ~/.bash_profile
  • tcsh: source ~/.tcshrc

The PATH environment variable

The PATH environment variable allows easy access to several programs. If it already has a value, you should add the new value(s) to the beginning of the existing one using a colon ":" as separator, and referencing the existing value using the variable itself, e.g.:

To add the values:

/home/brino/mysql/bin:/home/brino/apache-ant-1.7.0/bin

Edit the appropriate configuration file by adding a new line, at the bottom:

• bash (~/.bash_profile)

export PATH=/home/brino/eurovodca/mysql/bin:/home/brino/eurovodca/apache-ant-1.7.0/bin:${PATH}

• tcsh (~/.tcshrc)

setenv PATH /home/brino/eurovodca/mysql/bin:/home/brino/eurovodca/apache-ant-1.7.0/bin:${PATH}

Acknowledgments

These instructions were based upon PreparationLinux