Proteios 2 Installation

Description

This note describes issues regarding installation of Proteios 2 from a compiled copy of the project.

Note! This Wiki page is under construction. Its contents may change during development of the software, and instructions on this page should therefore be used with caution before the official Proteios 2 release.

Terms used

DBMS

Database Management System, e.g. MySQL.

SQL

Structured Query Language. Standard protocol for managing a DBMS.

SDK

Software Development Kit

J2SE

Java 2 Standard Edition

JDK

J2SE Development Kit

Requirements

Proteios 2 Project Copy

These instructions assume that a compiled copy of Proteios 2 already exists on the system. The installation should be performed from the directory containing the installation scripts, e.g. install-linux.sh, whether these are used or not. This directory will be referred to as the distribution directory. If Proteios 2 has been downloaded as source code and compiled on the system, it is the dist directory relative to the Proteios-2 installation directory.

Installed Applications

1. A DBMS must be installed (default is MySQL). In order to install Proteios, the DBMS server must be running during the installation (in case of MySQL, the daemon mysqld), so the DBMS can be accessed. In addition, the path for the DBMS program (mysql for MySQL) must allow it to be run from the distribution directory.
2. Java SDK (JDK) version 5 or newer must be installed. Java can be downloaded for free; see information on ​http://java.sun.com/. The version to download is SDK for Java 2 Platform Standard Edition 5.0 or newer (make sure that you download the JDK, and not just the JRE, the J2SE Runtime Environment).
3. Apache Tomcat servlet container needs to be installed in order for Proteios to work. Tomcat can be downloaded for free; see information on ​http://tomcat.apache.org/.

Information Needed

Information Needed on the Current System

1. DBMS username and password for a database manager with privileges to create and drop databases, as well as creating accounts on the DBMS.
2. Tomcat installation directory, if the installation program/script cannot determine it from the value of environment variable CATALINA_HOME (Catalina is the name of a Java class in the Tomcat package). If you need to find the directory yourself, first search for a directory with "tomcat" in the name. The "Catalina home" directory is the one with a sub-directory named "webapps".

Settings for Proteios made During Installation

1. Name of database for Proteios to use on the DBMS.
2. DBMS username and password that the Proteios application can use to connect to the DBMS.
3. Password that should be used for the root account in Proteios. The root account is used to add/delete users, groups, and roles in Proteios.

Description of Installation Steps

Example Setup

On many systems the installation procedure can be performed by running a program or script, and is in that case the recommended way to install the Proteios package. In this section the different steps in the setup are described, and an example of each step is provided. The example is based on the following assumptions:

Operating system	Unix/Linux?
DBMS used	MySQL
Database manager's DBMS username	caesar
Database manager's DBMS password	spqr
Name of database to use	proteios_db
Proteios' DBMS username	cicero
Proteios' DBMS password	palatium
Proteios' root account password	protagoras
Tomcat installation directory	/usr/local/packages/apache-tomcat-5.5.15/
Proteios-2 installation directory	/usr/local/packages/Proteios-2.0/

Example setup.

Alternative 1 - Installation using Script

This section describes the installation using the Linux installation script install-linux.sh in the distribution directory (for a source code distribution compiled on the local system using the example setup, this is /usr/local/packages/Proteios-2.0/dist). Move to this directory and start the installation by typing install-linux.sh in the command shell. Enter requested information when prompted. A value inside square brackets [] denotes a default value, that will be used if just pressing <Return> (in the case of [Y|n], the value in upper-case denotes the default, in this case 'Y').

For a more detailed description of the steps performed by the script, please see section Alternative 2 - Installation in Steps.

Steps in Installation using Script

Values entered by the user is shown in monospace font.

1. Enter username with create privileges on your DBMS.
   Username [root]: caesar
   Password: spqr (Not shown on console)
2. Configure the database name and user that proteios will use to connect to your DBMS.
   Database name [proteios]: proteios_db
   Username: cicero
   Password: palatium (Not shown on console)
3. Enter a password for the root account in proteios.
   Password: protagoras (Not shown on console)
   
   Thank you! Letś continue with the installation.
   
   Do you want to drop the existing 'proteios_db' database[Y|n]? Y
   Dropping database...done
   Updating proteios *.config files in proteomics/WEB-INF/classes
   [0%] Building database....................................
   [30%] Database built successfully.
   [35%] Initializing database...
   [37%] --Creating quota types...
   ...
   [79%] --Creating news...
   [90%] Database initialised successfully.
   
   
4. Let's deploy the webapplication into tomcat.
   
   Deploying proteios into /usr/local/packages/apache-tomcat-5.5.15
   
   proteios is now installed. Start tomcat before use.

To use Proteios, start a web browser on the system the installation was performed on and access the link:

http://localhost:8080/proteios/

Alternative 2 - Installation in Steps

In order for the examples to be brief, the operations are given as commands on a command line. It should be noted that it is not in general recommended to perform all operations in this way, as user names and passwords may easily become exposed.

Steps in Installation

1. The Proteios installation is performed from the distribution directory (for a source code distribution compiled on the local system using the example setup, this is /usr/local/packages/Proteios-2.0/dist). This will be assumed to be the working directory if not otherwise stated.
2. [Optional] Delete ("drop" in SQL parlance) the existing database to use. Example command:
   
   mysql -u caesar -p spqr -e DROP DATABASE IF EXISTS `proteios_db`;
   
   
3. Create the database to use, if it doesn't already exist. Example command:
   
   mysql -u caesar -p spqr -e CREATE DATABASE IF NOT EXISTS `proteios_db` DEFAULT CHARACTER SET utf8;
   
   
4. Set full access rights for the database to the Proteios application. Example command:
   
   mysql -u caesar -p spqr -e GRANT ALL ON `proteios_db`.* TO 'cicero'@'localhost' IDENTIFIED BY 'palatium'; FLUSH PRIVILEGES;
   
   
5. The Proteios configuration file proteios.config is updated with the username and password to use to connect to the DBMS. The configuration file is located in directory proteomics/WEB-INF/classes. In the example setup used, the configuration file is:
   
   /usr/local/packages/Proteios-2/dist/proteomics/WEB-INF/classes/proteios.config
   
   When Proteios later is deployed into the Tomcat installation webapps directory, this will in the example correspond to the file:
   
   /usr/local/packages/apache-tomcat-5.5.15/webapps/proteios/WEB-INF/classes/proteios.config
   
   The entries that are updated using the example values are:
   
   db.username = cicero
db.password = palatium
   
   
6. The Java class path variable is created by first adding the directory ./proteomics/WEB-INF/classes. Java archive files (*.jar) in directory ./proteomics/WEB-INF/lib/ is then listed and appended to the class path, separated by a character specific for the operative system (':' on Unix/Linux?, ';' on Microsoft Windows, where in addition directories are separated with '\' instead of '/', although Java does not seem to be sensitive to this). Example command (the command line has been broken into several lines for clarity and shortened in order to save space):
   
   CP=./proteomics/WEB-INF/classes
:./proteomics/WEB-INF/lib/antlr-2.7.6rc1.jar
:./proteomics/WEB-INF/lib/asm-attrs.jar
...
:./proteomics/WEB-INF/lib/xml-apis.jar
   
   
7. The Proteios database installation java program InitDB.class in package org.proteios.install is then run with the previously created class path and with the root account password as argument. Example command (the command line has been broken into several lines for clarity and shortened in order to save space):
   
   java -server -cp ./proteomics/WEB-INF/classes
:./proteomics/WEB-INF/lib/antlr-2.7.6rc1.jar
:./proteomics/WEB-INF/lib/asm-attrs.jar
...
:./proteomics/WEB-INF/lib/xml-apis.jar
org.proteios.install.InitDB protagoras
   
   
8. Proteios is deployed into the Tomcat installation webapps directory by creating a symbolic link named proteios pointing to the proteomics directory of the Proteios package. Example commands:
   
   cd /usr/local/packages/apache-tomcat-5.5.15/webapps
ln -s /usr/local/packages/Proteios-2.0/dist/proteomics proteios
   
   
9. The Proteios installation is now completed. Start Tomcat before use. To use Proteios, start a web browser on the system the installation was performed on and access the link:
   
   http://localhost:8080/proteios/
   
   

This concludes the tour of the Proteios installation. Please visit the gift shop on your way out.