Skip to content

setup_guide.md

Latest commit

 

History

History
143 lines (79 loc) · 5.84 KB

setup_guide.md

File metadata and controls

143 lines (79 loc) · 5.84 KB

Setup guide

This is a setup guide for the PiMP pipeline. It contains instructions for Linux (tested on Ubuntu 15.04 & Fedora 21) and Mac OS X Yosemite.

0. git Setup

To work with large binary files in the repository install git-lfs

$ brew install git-lfs

In the repository, run these commands

$ git config --add lfs.url "http://poisson.tcrc.gla.ac.uk/polyomics/pimp.git/info/lfs"
$ git lfs install

(Linux)

$ git config --global credential.helper 'cache --timeout=36000'

(OS X)

$ git config --global credential.helper osxkeychain

1. System Setup

Java

Install Java version 8, or make sure it is installed (run java -version from the command line to check).

(Linux) Linux often comes with OpenJDK pre-installed by default but it's probably better to get Oracle's JDK.

(OS X) Install Java via Homebrew (brew update && brew cask install java)

R

Install R version 3.2, or make sure it is installed (run R --version from the command line to check).

(Linux) Install R via your package manager

(OS X) R can easily be installed via Homebrew

Python

Install Python version 2.7, or make sure it is installed (run python --version from the command line to check).

(Linux) Python should already be installed.

(OS X) Python should already be installed.

RabbitMQ

We need to set up a message queuing server to handle batch jobs. Install RabbitMQ for this. Version 3.5.6 was used for development.

(Linux) Install via your package manager or from the website above.

(OS X) Install via homebrew (brew install rabbitmq)

Tools and Libraries

Compilation tools and libraries are needed by some of the dependencies in the system.

  1. (OSX) Install the XCode command line tools and various libraries.

     $ xcode-select --install
 $ brew install mysql netcdf gcc48 xquartz openssl
 $ brew link openssl

  2. (Ubuntu) Install various libraries.

     $ sudo apt-get install libmysqlclient-dev libxml2-dev libxslt1-dev libcurl4-openssl-dev libssl-dev libnetcdf-dev libfreetype6-dev libatlas-base-dev libpython-dev

  3. (Fedora) Install various libraries.

     $ sudo yum install mysql-devel libxml-devel libxslt-devel cmake qt-devel qt-config
 $ ln -s /usr/bin/qmake-4 /usr/bin/qmake # workaround ..

2. Setting up PiMP

  1. Go to the django_projects\pimp directory and copy one of the example environment files to the .env file. The example-dev.env file contains an environment you might want to set during development, whilst the example-prod.env file contains an environment more suitable for production. E.g.

     $ cp example-dev.env .env

  2. Edit the .env file for your environment

(OS X) Getting rJava to install can be a pain. One method that works is to run R with the correct environment variables; firstly run the following command:

JAVA_CPPFLAGS="-I/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/include \
-I/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/include/darwin" \
JAVA_LIBS="-L/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/jre/lib/server -ljvm" \
sudo R CMD javareconf

Then, running the following command will run a subshell with the correct environment variables set; do all the rest of the installation steps from this subshell:

JAVA_CPPFLAGS="-I/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/include \
-I/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/include/darwin" \
JAVA_LIBS="-L/Library/Java/JavaVirtualMachines/jdk1.8.0_51.jdk/Contents/Home/jre/lib/server -ljvm" \
R CMD javareconf -e

Obviously, the correct directories for the header files and libraries need to be specified.

  1. Run the following command in the project root directory

     $ ./gradlew setupPiMP

3. Running PiMP

The initial PiMP setup created a virtual environment in venv in the project root directory. To enter the virtual environment there is a script you can run.

  1. From the project root directory run

     $ . venv/bin/activate

    You will know you are in the virtual environment, because your prompt will change. You can exit the virtual environment by running deactivate.

  2. Whilst in the virtual environment change to the django_projects/pimp directory and run

     $ honcho start

4. Setting up Python for development work

  1. Install virtualenvwrapper for python. This lets you work in a Python virtual environment -- useful to prevent package conflicts etc.

     $ pip install virtualenvwrapper

  2. Add the following lines to your shell startup file (~/.bashrc) to set the location where the virtual environments should live (WORKON_HOME) and the location of your development project directories (PROJECT_HOME). Save the changes to ~/.bashrc.

     export WORKON_HOME=$HOME/.virtualenvs
 export PROJECT_HOME=$HOME/git/pimp
 source /usr/bin/virtualenvwrapper.sh

  3. Reload .bashrc and create the directory to hold the virtual environments.

     $ source ~/.bashrc
 $ mkdir -p $WORKON_HOME

5. Quick Start Database for FrAnK developers

A sample SQLite database is provided at $PROJECT_HOME/django_projects/test_data/testdb.db. This file contains several fragmentation sets which can be readily annotated by any new annotation tool you've developed. To use this, copy testdb.db to replace the sqlite db you'd created during migrate (in step 5), e.g.

    (venv)$ cp $PROJECT_HOME/django_projects/test_data/testdb.db $PROJECT_HOME/django_projects/pimp/sqlite3.db

Use the user id "testuser" and password "testuser" for login later.