Install PeakForest locally

Installation - from scratch

About this document

This support is used to configure a computer to run PeakForest webapps. This webapps require a specific environment configuration (java / tomcat version, OpenBabel, ...). We recommande you to use the same softwares version as specified below.

To just run PeakForest on any computer, use the docker version.

If you have any trouble, please refer to the ref. Docker image building scripts.

Requirements

  • Hardware: see tab below
  • Operating system: Ubuntu 14.04 LTS
resource Minimal Recommended
Processor 2 Ghz ≥ 2.4 Ghz
Processors number 2 ≥ 4
Memory 8 GB ≥ 16 GB
Disk space 50 GB ≥ 500 GB

Install and configure third part softwares

Tomcat install and configuration

First install Apache Tomcat (if not done in previous step) and install the tomcat7-admin package.

# if you did not install Tomcat during the install,
# you must install it with this command:
sudo apt-get install tomcat7
# you shall install these additional packages in
# order to administrate you server:
sudo apt-get install tomcat7-docs tomcat7-admin tomcat7-examples

By default, users are not activated in Tomcat. Edit the file /var/lib/tomcat7/conf/tomcat-users.xml (e.g. with nano or vi editor) as root (sudo user).

<tomcat-users>
   <!--
   # DO NOT EDIT THE BEGINNING OF THE FILE
   # edit me with:
   # sudo nano /var/lib/tomcat7/conf/tomcat-users.xml
   # save me with ctrl+o / ctrl+x
   -->
   <role rolename="manager-gui"/>
   <role rolename="admin-gui"/>
   <user username="peakforest"
      password="ENTER_A_STRONG_PASSOWRD"
      roles="manager-gui,admin-gui"/>
</tomcat-users>

Notes:

you can encrypt the password in this file. Just add a "digest" attribute on "Realm" markup (the one matching UserDatabaseRealm configuration) with "sha-256" as value in /var/lib/tomcat7/conf/server.xml file. Then run the following command to hash your password: /usr/share/tomcat7/bin/digest.sh -a sha-256 ENTER A STRONG PASSOWRD. It should return "yourPasswordNotHashed:yourPasswordHased"; Copy your hashed password and past it as "password" attribute value in /var/lib/tomcat7/conf/tomcat-users.xml file. After restarting the tomcat server, you can access to the Tomcat manager at the URL: http://servername:8080/manager/html (enter the login and the password setting in the config. file).

To download PeakForest generated files, you must create a virtual host named "peakforest generated files".

# create generated files directory / virtual host
sudo mkdir /var/lib/tomcat7/webapps/peakforest_generated_files
sudo chown tomcat7:tomcat7 /var/lib/tomcat7/webapps/peakforest_generated_files

Java install and configuration

Java JDK is requiered to build Open Babel (see this section below).

Install Java and set environment variable:

# add java-8 repository
sudo add-apt-repository ppa:openjdk-r/ppa -y
sudo apt-get update
# install java JDK
sudo apt-get install openjdk-8-jdk
# add JAVA_HOME as environment variable
echo "export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/" >> ~/.bashrc
# load new environment variable for current bash session
source ~/.bashrc

It is very important when you install Open Babel to have JAVA HOME as environment variable. Check with a echo $JAVA HOME if the variable is setted (must not return a blank result).

Note: you have to install other software / libraries / packages. The procedure is described below.

:warning: You need to edit Tomcat7 configuration so it can use Java-8. Open the Tomcat service manager script with sudo nano /etc/init.d/tomcat7 and add the following section

...
if [ 'id -u' -ne 0 ]; then
echo "You need root privileges to run this script"
exit 1
fi

# ADD THIS SECTION - DO NOT EDIT THE CODE BEFORE
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/
# END ADD THIS SECTION - DO NOT EDIT THE CODE AFTER

# Make sure tomcat is started with system locale
if [ -r /etc/default/locale ]; then
# ...

Database install and configuration

First install MySQL. You can either install it on the same server (recommended) or on an other one (make sur that the machine hosting PeakForest has access to it through the network).

Install MySQL with this command:

# install MySQL if not already done...
sudo apt-get install mysql-server mysql-client libmysqlclient15-dev mysql-common
# ... set admin password & cie.
# enter MySQL command line tool
mysql -u root -p

Then execute the following SQL code to create Peak Forest MySQL user and database. Remember the password chose for the MySQL user "peakforest": it will be required later.

CREATE DATABASE peakforest CHARACTER SET UTF8;
CREATE USER 'peakforest'@'localhost' IDENTIFIED BY 'ENTER_A_STRONG_PASSWORD';
GRANT ALL PRIVILEGES ON peakforest.* TO 'peakforest'@'localhost';
FLUSH PRIVILEGES;

Notes:

  • feel free to use MariaDB or any fork of MySQL; however if you encounter a problem, we may not be able to help you.
  • you do not need to create any database table: they will be initialized by the PeakForest main webapp on first run.

Configure system paths

Paths and directories for PeakForest webapps:

# PeakForest files
sudo mkdir -p                    \
     /peakforest                 \
     /peakforest/bin             \
     /peakforest/data            \
     /peakforest/logs            \
     /peakforest/tools           \
     /peakforest/data/svg        \
     /peakforest/data/mol        \
     /peakforest/data/json       \
     /peakforest/data/cpd-numbered        \
     /peakforest/data/nmr_spectra         \
     /peakforest/data/nmr_spectra/raw     \
     /peakforest/data/nmr_spectra/images
# set correct files authorizations
sudo chown -R tomcat7:tomcat7 /peakforest
sudo chown -R peakforest:tomcat7 /peakforest/tools
# PeakForest upload files directory
sudo mkdir /var/lib/tomcat7/peakforest_uploaded_files
sudo chown tomcat7:tomcat7 /var/lib/tomcat7/peakforest_uploaded_files

Install and configure OpenBabel versions

OpenBabel is a chemical toolbox designed to speak the many languages of chemical data. This open and powerful tool is used in Peak Forest to extract all data from a compound (monoisotopic mass, average mass, structures, formula, ...) from the InChI format. We chose Ubuntu because most part of third part libraries used by Open Babel can be installed with the aptitude package manager. If you use a RedHat or BSD server you must follow the instructions to install OpenBabel on their website.

Install third-part libraries

The following packages are required to build and install Open Babel on your computer (Ubuntu 14.04):

sudo apt-get install \
     gcc cmake wx-common wx2.8-headers libwxbase2.8-dev libxml2    \
     libxml2-dev zlib1g-dev zlib1g-dev libcairo2-dev libeigen2-dev \
     build-essential g++ libeigen3-dev python-dev libperl-dev      \
     libcurl4-openssl-dev zlib1g-dev checkinstall libwxgtk2.8-dev xterm git

Install OpenBabel release 2.3.2 with java library

OpenBabel 2.3.2 is used by PeakForest-WebApp to gather compound basic data (formula, monoisotopic mass, smiles, ...) form the InChI.

# download Open Babel 2.3.2
cd /tmp/
wget http://sourceforge.net/projects/openbabel/files/openbabel/2.3.2/openbabel-2.3.2.tar.gz/download
mv download download.tar.gz && tar zxf download.tar.gz
# move source files
mv openbabel-2.3.2/ ~/ && cd ~/
mkdir build_openbabel_2.3.2 && cd build_openbabel_2.3.2
# build OpenBabel
cmake ../openbabel-2.3.2 -DJAVA_BINDINGS=ON
make -j2
sudo make install

:warning: You need to edit Tomcat7 configuration so it can use OpenBabel binary from Java bundle. Open the Tomcat service manager script with sudo nano /etc/init.d/tomcat7 and add the following section

...
if [ 'id -u' -ne 0 ]; then
echo "You need root privileges to run this script"
exit 1
fi

# ADD THIS SECTION - DO NOT EDIT THE CODE BEFORE
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/
# END ADD THIS SECTION - DO NOT EDIT THE CODE AFTER

# ADD THIS SECTION - DO NOT EDIT THE CODE BEFORE
export CATALINA_OPTS="-Xms512M -Xmx1024M -Djava.library.path=/usr/local/lib"
# END ADD THIS SECTION - DO NOT EDIT THE CODE AFTER


# Make sure tomcat is started with system locale
if [ -r /etc/default/locale ]; then
# ...

Compile OpenBabel command line call with a specific path

This version of OpenBabel is used to generate the molecules mol files, svg images.

# download OpenBabel 40bc0f10
cd ~ && git clone git://github.com/openbabel/openbabel.git
cd openbabel && git checkout 40bc0f105c3d3dc7f189cd6d54ddfef6f5452dbf
# move source files
cd ~ && mv openbabel openbabel-40bc0f10
mkdir build_openbabel_40bc0f10 && cd build_openbabel_40bc0f10/
# build Open Babel
cmake ../openbabel-40bc0f10 -DCMAKE_INSTALL_PREFIX=/usr/local/bin/openbabel-40bc0f10
make -j2 # (may take a while... Fancy a coffee?)
sudo make install

NMRPro spectra viewer

The NMRPro tool is used for the visualization of NMR 1D Carbon-13 raw data in PeakForest. This python / django application has been packaged in a Docker container to avoid side effect / bug.

You will need to update settings.py and urls.py files.

# install NMRPro dependencies
sudo apt-get update &&\
    sudo apt-get install -y \
    python2.7      \
    python-numpy   \
    python-scipy   \
    python-pip   &&\
  pip install django==1.9.7  &&\
  pip install --allow-unverified numpy scipy patterns url &&\
  pip install nmrpro==0.2.7         &&\
  pip install django-nmrpro==0.2.4  &&\
  django-admin startproject nmrpro_server &&\
  sudo apt-get autoremove -y &&\
  sudo apt-get clean         &&\
  rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Setup NMRPro -> file changed
cp /path-to-custom-files/settings.py            nmrpro_server/nmrpro_server/settings.py
cp /path-to-custom-files/nmrpro_server/urls.py  nmrpro_server/nmrpro_server/urls.py

# RUN build
python /nmrpro_server/manage.py migrate

# symlink
sudo mkdir /spectrum
sudo ln -s /peakforest/data/nmr_spectra/raw /spectrum/raw
sudo ln -s /peakforest/data/nmr_spectra/raw /nmrpro_server/raw

# start NMRPro as a background job
python nmrpro_server/manage.py runserver 0.0.0.0:8000 >> /peakforest/logs/nmrpro.log 2>&1 &

The phantomjs tool is also necessary in order to generate spectra images.\ Download this folder and its content to install it on the host machine.

sudo cp /path-to-custom-files/phantomjs       /peakforest/tools/phantomjs