wiki:Installation

Proteios 2 Installation

Description

This note describes how to install Proteios Software Environment from a binary archive or compiled source code. The easiest way to install a Proteios SE server along with search engines and feature detection tools is probably to to use Ansible along with the scripts provided here. As an alternative, we now supply Proteios SE server images for Amazon Web Services and VMware.

Requirements

  1. Proteios SE distribution (binary archive or source code).
  2. A database management system (DBMS), i.e. MySQL, with an administrator account configured with password. We recommend MySQL version 5.1.x, since 5.5.x versions have been reported not to work with current Proteios.
  3. Java version 6 or higher (see http://java.com/).
  4. Apache Tomcat servlet container installed (see http://tomcat.apache.org/). Preferably the environment variable CATALINA_HOME should be set to point to the base directory of your Tomcat installation.

Note on Shell Interpreter on Unix/Linux Systems

Shell scripts *.sh in Proteios SE are designed to be interpreted using the bash shell (Bourne Again Shell). If the default shell /bin/sh is linked to bash, the scripts can be started from a command line by simply typing the script name and any options to use. Otherwise, please explicitly enter the shell name "bash" before the script name, e.g. for installation script install-linux.sh, instead of entering "install-linux.sh", enter "bash install-linux.sh", provided that bash links to the bash shell.

Note on CATALINA_HOME vs CATALINA_BASE

Originally the Tomcat executables were located in directories $CATALINA_HOME/bin/ and $CATALINA_HOME/lib/, while each servlet was located in its own directory under $CATALINA_HOME/webapps/. However, in order to allow more than one instance of Tomcat to run simultaneously, e.g. with different port numbers, environment variable CATALINA_BASE was introduced to specify the location of the webapps/ directory, where the servlets for a specific Tomcat instance were installed, while $CATALINA_HOME specified the location of the Tomcat application itself.

To start several Tomcat instances with different configurations, $CATALINA_BASE is first set to the location for the servlets, the Tomcat instance in question should use, after which Tomcat is started (often from a start-up script) with desired configurations for the instance, including port number. $CATALINA_BASE is then set to the location for the servlets, the next Tomcat instance should use, and a new Tomcat instance is started with new configuration, and so on. The current value of $CATALINA_BASE can therefore only be used to find the location of servlets, for the last Tomcat instance started (provided its value has not been changed after that).

Unlike $CATALINA_HOME, CATALINA_BASE is not intended to be set to a fixed value for a system and remain unchanged for a considerable time, but is intended to tell Tomcat and related scripts what subset of servlets a specific operation concerns. However, on systems where only one instance of Tomcat is used, $CATALINA_BASE will specify the location of the webapps/ directory, where servlets are installed. This gives the administrator freedom to have the Tomcat application installed in one place, and servlet code in another. Some Linux distributions like Ubuntu have different default locations for these, $CATALINA_HOME is /usr/share/tomcat6/, while $CATALINA_BASE is /var/lib/tomcat6/ for Tomcat version 6. For a Tomcat installation with both application and webapps directory under the same root directory, $CATALINA_BASE will have the same value as $CATALINA_HOME.

On development systems for Proteios SE 2.0.17 or earlier, $CATALINA_HOME should be set, while on Proteios SE 2.0.18 and later, $CATALINA_BASE should be set ($CATALINA_HOME may also be set). If you want Proteios SE to be installed under directory $CATALINA_HOME/webapps/proteios/, simply set $CATALINA_BASE to the same value as $CATALINA_HOME.

Quick Windows Install

  1. Unpack the binary archive or build Proteios SE from source code (see Build Proteios from Source Code).
  2. Stop the Tomcat service if it is running.
  3. Move to the directory containing the installation script install-win.bat for Windows. This is the directory you unpacked the binary archive in, or directory dist\ProteiosSE.2.* if Proteios SE was built from source code. It is recommended that the path for the directory does not contain any space characters.
  4. Run the installation script at a command prompt or by double-clicking and input requested information. You might need aAdministrator access in order to create new directories for Proteios SE user and temporary files and deploying the application in Tomcat (access to Tomcat subdirectory "webapps" is needed).
  5. Start Tomcat. Proteios SE can now be accessed from a web browser at http://localhost:8080/proteios/.
  6. The system is now up and running, but to get the most out of it you'd probably like to do some more server administration.

Note on Warning Messages

When installing or upgrading, a warning message might be written by the cache manager of the type:

WARN CacheManager::detectAndFixDiskStorePathConflict:271 - Creating a new instance of
CacheManager using the diskStorePath "/tmp" which is already used by an existing CacheManager.

This message can be ignored.

Quick Windows Update

  1. Unpack the binary archive or build Proteios SE from source code (see Build Proteios from Source Code).
  2. Stop the Tomcat service if it is running.
  3. Run the update_proteios-win.bat script at a command prompt or by double-clicking and input requested information. The script is found in the directory you unpacked the binary archive in, or directory dist\ProteiosSE.2.* if Proteios SE was built from source code.
  4. Stop tomcat

Detailed Instructions

Notes on Installed Software

  1. The DBMS server must be running during the Proteios 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 directory the installation is performed from.
  2. Java. The version to download is 6 or higher. If installation is from binaries, JRE, the Java Runtime Environment should be OK, but we recommend JDK (Java SE Development Kit), since we don't perform testing on JRE only systems. If you want to compile Proteios SE, or are planning to create your own extensions, you will need JDK.
  3. Tomcat must have "write" access to the directory for Proteios user files and the directory for Proteios temporary files. Furthermore, if the tomcat installation path contains space characters this can cause a problem for the default Proteios 2.0 installation (solved in 2.1 and higher versions), but there is a quick workaround.

Information Needed

Installed Packages

  1. DBMS username and password for a database manager with privileges to create and drop databases, as well as creating accounts on the DBMS. Note that if you are going to install the web application on a different server than the database server, you will need to make sure that the user has right to connect from the machine where you are putting the Proteios application. Instructions for mySQL remote access can be found here.
  2. Tomcat installation directory, if it cannot be determined 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".

Proteios Configuration (Set at 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.
  4. Location of directory for Proteios user files.
  5. Location of directory for Proteios temporary files.
  6. Control port number for Proteios FTP Server (see section FTP Communication Ports). If in doubt, use default setting 8021.
  7. Allowed port number range for Proteios FTP Server passive connections (see section FTP Communication Ports), given as "min,max", e.g. 2000,2500, or left blank if no restrictions exist.
  8. Outgoing mail server for Proteios notification e-mail.
  9. "From"-address for Proteios notification e-mail (normally "noreply@" + system name).

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
DBMS computer host name or IP number localhost (same as Proteios is installed on)
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
Directory for Proteios' user files /usr/local/proteios/files/
Directory for Proteios' temporary files /usr/local/proteios/temp/
Control port for Proteios FTP Server 8021
Passive port range for Proteios FTP Server 2000,2500
Outgoing mail server mail.example.com
"From"-address for notification e-mail noreply@example.com
Tomcat installation directory /usr/local/packages/apache-tomcat-5.5.15/
Proteios-2 installation directory /usr/local/packages/Proteios-2.0/

Example setup.

Summary - What Happens During Proteios Installation

Proteios is a web application. It uses Tomcat to be accessed through a web browser, and it uses a database to store its data. Below is a summary of the installation procedure.

  1. The supplied information on the DBMS host name and manager account (username caesar and password spqr in the example) is used to create a database with the specified name (proteios_db in the example).
  2. A new DBMS account (username cicero and password palatium in the example) is set up on the newly created database.
  3. Information on the new DBMS account is stored in a configuration file, so Proteios can use it to access the database later on. Information on directory for user files, outgoing mail server, and notification e-mail "from"-address is also stored in this configuration file.
  4. Information on directory for temporary files is stored in configuration file web.xml.
  5. Information on control port and passive port range for Proteios FTP Server is stored in configuration file ftp.properties.
  6. X!Tandem search configuration file xtandem.properties is created if not existing.
  7. Log configuration file log4j.properties is created if not existing.
  8. The database is prepared for storing data on Proteios users, groups, experimental data, and other topics. Initially, it only contains the Proteios root account (with password protagoras in the example), that is used to create all other accounts in Proteios, from which proteomics data can be stored. If a database already exists, you have the option to update instead of dropping it, thus keeping/adjusting stored records (however, please see Restrictions for database structure update).
  9. The directory for user files is created, if not existing.
  10. The "conf" directory in the user files directory is created, if not existing.
  11. The directory for temporary files is created, if not existing.
  12. The Proteios FTP Server start script is created from a template file by copying in the name of the Tomcat installation directory.
  13. When the DBMS setup is finished, Proteios is prepared for use by being deployed into Tomcat, either by copying a number of files to the Tomcat webapps directory, or, preferrably, by creating a link between the latter and a directory with the Proteios files.
  14. After the installation is finished, start Tomcat if not already running. Proteios can now be accessed from a web browser through http://localhost:8080/proteios/. If the installation is correct, the browser will be re-directed to the Proteios log-in page. To log in for the first time, use username root and the accompanying password (protagoras in the example).

Some comments regarding the installation

  • The DBMS manager account is only used to prepare the DBMS, and information on this account (username caesar and password spqr in the example) is not stored by Proteios in its configuration files. The account is not affected by the installation, and it remains on the DBMS afterwards.
  • The DBMS account that the installation prepares for Proteios' internal use (username cicero and password palatium in the example), will not normally be used by human users. It is therefore not necessary that the username and password are easy to remember, so more or less cryptical choices like gh45jsd8765j and k5f89n could be used in principle. As there is no difference between this account and other from the DBMS point of view, you might want to use non-trivial choices for the username and password, to make sure that the account is not used to access data directly via a DBMS client program.
  • It is recommended to avoid spaces in directory names, if possible. Even though the installation script might work as intended, the application has not been fully tested using spaces in directory names.

Restrictions for database structure update

Some changes in database structure cannot be performed by updating an existing database and adjusting stored records. One example is addition of columns with property not-null="true".

Alternative 1 - Installation from Script

This section describes the installation using the Linux installation script install-linux.sh. Move to directory dist, which contains the installation script. 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 from Command Line.

Installation from Script Step-by-Step

Values entered by the user is shown in monospace font.

  1. Enter host name and user name with create privileges on your DBMS.
    Host name [localhost]:
    Username [root]: caesar
    Password: spqr (Not shown on console)
  2. Enter a password for the root account in proteios.
    Password: protagoras (Not shown on console)
  3. 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)
  4. Select a directory for proteios to use for user files.
    User files directory [/usr/local/proteios/data]: /usr/local/proteios/files
  5. Select a directory for proteios to use for temporary files.
    Temporary files directory [/usr/local/proteios/tmp]: /usr/local/proteios/temp
  6. Select control port for proteios FTP Server.
    FTP Server Control Port [8021]: 8021
  7. Set optional passive port range for proteios FTP Server (min,max or blank).
    FTP Server Passive Port Range []: 2000,2500
  8. Set outgoing mail server for proteios notification e-mail.
    Mail server []: mail.example.com
  9. Set "from"-address for proteios notification e-mail.
    Mail "from"-address [noreply@…]:

    Thank you! Letś continue with the installation.

    Do you want to update an existing 'proteios_db' database[y|N]? N
    Do you want to drop an existing 'proteios_db' database[y|N]? Y
    Dropping database...done
    Updating proteios *.config files
    Updating proteios web.xml file
    Updating proteios ftp.properties file
    Creating X!Tandem search config file xtandem.properties...
    Creating log config file log4j.properties...
    [0%] Building database....................................
    [30%] Database built successfully.
    [35%] Initializing database...
    [37%] --Creating quota types...
    ...
    [79%] --Creating news...
    [90%] Database initialised successfully.
    Creating user files directory... done
    Creating "conf" directory in user files directory... done
    Creating temporary files directory... done

  10. Let's deploy the webapplication into tomcat.

    Updating Proteios FTP Server start script

    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 from Command Line

The operations are here 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.

Installation from Command Line Step-by-Step

  1. The installation should be performed from the directory in the Proteios 2 distribution containing the installation scripts, e.g. install-linux.sh, whether these are used or not. 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 (/usr/local/packages/Proteios-2.0/dist in the example). 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 database name, username and password to use to connect to the DBMS, and location of directory for storing user files. The configuration file is located in directory www/WEB-INF/classes. In the example setup used, the configuration file is:

    /usr/local/packages/Proteios-2.0/www/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.url = jdbc:mysql://localhost/proteios_db
    db.username = cicero
    db.password = palatium
    userfiles = /usr/local/proteios/files
    mail.server.host = mail.example.com
    mail.from.address = noreply@example.com

  6. The Proteios configuration file web.xml is updated with the directory location for storing temporary files. The web.xml file is located in directory www/WEB-INF/. In the example setup used, the configuration file is:

    /usr/local/packages/Proteios-2.0/www/WEB-INF/web.xml

    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/web.xml

    The entry that is updated using the example value is:

    <init-param>
    <param-name>temporary.file.repository</param-name>
    <param-value>/usr/local/proteios/temp</param-value>
    </init-param>

  7. The Proteios FTP Server configuration file ftp.properties is updated with the control port and passive port range. The ftp.properties file is located in directory www/WEB-INF/classes. In the example setup used, the configuration file is:

    /usr/local/packages/Proteios-2.0/www/WEB-INF/classes/ftp.properties

    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/ftp.properties

    The entries that are updated using the example values are:

    PORT_NR=8021
    PASSIVE_PORT_RANGE=2000,2500

  8. The X!Tandem search configuration file xtandem.properties is created from template file xtandem.properties.in, if the former does not exist. The xtandem.properties file is located in directory www/WEB-INF/classes. In the example setup used, the configuration file is:

    /usr/local/packages/Proteios-2.0/www/WEB-INF/classes/xtandem.properties

    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/xtandem.properties

  9. The log configuration file log4j.properties is created from template file log4j.properties.in, if the former does not exist. The log4j.properties file is located in directory www/WEB-INF/classes. In the example setup used, the configuration file is:

    /usr/local/packages/Proteios-2.0/www/WEB-INF/classes/log4j.properties

    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/log4j.properties

  10. The Java class path variable is created by first adding the directory ./www/WEB-INF/classes. Java archive files (*.jar) in directory ./www/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=./www/WEB-INF/classes
    :./www/WEB-INF/lib/antlr-2.7.6rc1.jar
    :./www/WEB-INF/lib/asm-attrs.jar
    ...
    :./www/WEB-INF/lib/xml-apis.jar

  11. 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 ./www/WEB-INF/classes
    :./www/WEB-INF/lib/antlr-2.7.6rc1.jar
    :./www/WEB-INF/lib/asm-attrs.jar
    ...
    :./www/WEB-INF/lib/xml-apis.jar
    org.proteios.install.InitDB protagoras

    In the case when an existing database is not dropped before initialization, program InitDB.class is run with extra argument update:

    ...
    org.proteios.install.InitDB update protagoras

  12. The directory for user files is created if not existing. If it could not be created, the user is instructed to create the directory by hand. Example commands:

    mkdir -p /usr/local/proteios/files

  13. The directory for temporary files is created if not existing. If it could not be created, the user is instructed to create the directory by hand. Example commands:

    mkdir -p /usr/local/proteios/temp

  14. The Proteios FTP Server start script start_proteios_ftp_server.sh is created from template file start_proteios_ftp_server.sh.in, by copying in the name of the Tomcat installation directory. The start_proteios_ftp_server.sh file is created in the directory the installation is run from. Under Linux/Unix?, the created script file is made executable:

    chmod ugo+x start_proteios_ftp_server.sh

  15. Proteios is deployed into the Tomcat installation webapps directory by creating a symbolic link named proteios pointing to the www 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/www proteios

  16. 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.

Last modified 10 months ago Last modified on Jun 30, 2016, 10:38:20 AM