PLEASE NOTE: these instructions are for the install of tranSMART version 1.2.4; they will be updated when version 1.2.5 is released. 

Overview

These instructions are based on the assumption that you are installing tranSMART version 1.2.4 on Ubuntu 14.04. They draw heavily on previous versions, see the credits section of this document for details.

The instructions come it two flavors (1) instructions for an all-in-one script and (2) more detailed step-by-step instructions. The step-by-step instructions are useful when you need to see what is going on and possible correct problems. The step-by-step instructions are also a helpful guide for the installation process on other platforms.

As an overview, the install process implements these four steps. For the step-by-step instructions,follow each step in order, reading each step completely. Expect the process to take several hours (depending on the speed of your internet connection, the power of your machine, and the speed of your machine's memory and disk). You can also see these steps in the comments of the all-in-one script.

1. You will need the set up the necessary support tools (some basic unix command-line tools, PostgreSQL, Grails, Tomcat, R, RServe, and SOLR).
2. You will need to set the database (PostgreSQL is used in these instructions - tranSMART also runs on Oracle)
3. You will need to download and copy the release war files to tomcat.
4. And you will need to start all the parts of the system

Optionally, there is a set of R-Based modules that connect to the application's REST interface; these can also be used to connect to the database, search for and select data, and to perform analysis.

If you get stuck, reach out to the community. The best ways to get answers are by using hipchat or tranSMART google groups. Likely someone else has had the same problem. Here is a link for registering with hipchat. Use transmart-release group when you are in hipchat. If you learn anything that should be added to this page, please leave a comment!

There is also a Sanity Checklist for a fully functional system, to make sure that everything was correctly installed and it running properly. This may help you pinpoint problems. 

Hardware and OS Requirements

The requirements vary based on your specific needs. Since these instructions are aimed at producing a demonstration system for review and evaluation, we are assuming very modest requirements, for example, no more than 100 subjects, a couple of studies with genomic data, and fewer than 10 users; in this case, you can combine the app server with the database server into a single VM or a standalone server with at least the following specs:

• CPU: Dual core
• Memory: 4 to 8GB (8 preferred; will work is a little as 2GB)
• Storage: 50 GB (for more studies increase the size of the disk memory)
• OS: linux (these instructions assume: Ubuntu 14.04).

All-in-one instructions

These first set of instructions, for running the all-in-one script, guides you in seting up a Scripts folder on the home directory of an account with sudo privilages (such as the ubuntu's administration account that is established when you initialize your OS). From this folder you can run the install script that will install all of the support command line tools, required support directories, PostgreSQL, R and Rserve, required R packages, SOLR and the SOLR web interface, and the transmart war files in Tomcat 7. In addition it sets up the transmart database and loads a demo set, GES8581. Upon completion of the install you can (optionally) run a set of checking scripts that will check to make sure everything is installed correctly and running properly.

Run the following commands in the home directory of the account that you are going to use to run transmart (also see these commands in the attached install script). The install will run for an hour or more depending on the speed of your connection, memory, and disk.

sudo apt-get update
sudo apt-get install -y git
git clone https://github.com/tranSMART-Foundation/Scripts.git
Scripts/install-ubuntu/InstallTransmart.sh 2>&1 | tee install.log

Once the install is complete, you can test to see if the install was successful (see also the attached check script). By using the following commands

cd ~/Scripts/install-ubuntu/checks/
./checkAll.sh 2>&1 2>&1 | tee ~/checks.log

Review the log file, checks.log, in your home directory. Also, open a browser to http://localhost:8080/transmart/ where you should see a login page. See the section on using the web application, towards the end of this document. To restart the needed tool interfaces (after a reboot, for example) see the section on Running SOLR, Rserve, and Tomcat.

Step-by-step Instructions

The rest of this document gives instructions for a step by step series of commands (which are also implemented by the all-in-one script) to better illustrate what is going on and give installers of transmart more opportunity to tune or modify the instructions to particular needs. In addition, seeing the detail of the install process may help you in debugging problems. Finally, it is instructive to go through the process of the install by yourself, in you have the time and inclination. 

Installing Support Tools

The support tools are, generally, unix command line tools. In the instructions that follow, we assume that your installing on the latest LTS version of Ubuntu (currently, Ubuntu 14.04) and are using the command line interface. Since the final product of these instructions is run in the browser, it is assumed that you have loaded (or are using) the desktop version of Ubuntu.

Setup

Following tools and frameworks are required prior to installing and running TranSMART. These instructions use Ubuntu's apt-get command to install the supporting tools for the subsequent install of tranSMART. We assume that you are installing on a clean Ubuntu OS. To build Ubuntu OS in a VM, see the instructions at Ubuntu or search "installing Ubuntu on a VM".

Also, at least in this context, where you are setting up tranSMART for an introduction and exploration, it is a good idea to set up the initial (root) user as the user that will run the application. You can choose the name and password when you do the install, for example the user we use in these instructions is: name = transmart, password = transmart.

Basics

In this case, for the Ubuntu OS, there is predefined method for installing rsync, curl, tar, Java (JDK), php, PostgreSQL, a make file in the transmart-data archive will load these required tools. However, we will install curl separately, as below, to load and extract transmart-data; so that we can run the script. The command line steps below will do the following:

• Create a folder, transmart, to contain the app, scripts, and data

• Within that folder, using curl, download the https://github.com/tranSMART-Foundation/transmart-data/archive/release-1.2.4.zip. 
• Expand that zip file into ~/transmart/transmart-data
• Within that folder run the initial setup commands (these instructions are basicially from the file ~/transmart/transmart-data/README.md)
• Run additional commands to install ant and maven

mkdir ~/transmart
cd ~/transmart
sudo apt-get install -y curl
curl https://codeload.github.com/tranSMART-Foundation/transmart-data/zip/release-1.2.4 -o transmart-data-release-1.2.4.zip
unzip transmart-data-release-1.2.4.zip
mv transmart-data-release-1.2.4 transmart-data
cd transmart-data
sudo make -C env ubuntu_deps_root
make -C env ubuntu_deps_regular
sudo apt-get install -y ant
sudo apt-get install -y maven

NOTE: There is an error in the scripts above that installs the wrong version of groovy; this error will need to be fixed in the next release of the scripts. For now, this command-line, coupled with the install of groovy 2.4.5 in the next section is a work-around.

rm ~/transmart/transmart-data/env/groovy

In the following instructions, it will be necessary to edit configuration files. We are using the visually enhanced version of vi called vim.  Feel free to us another editing tool. If you wish to closely follow the editing instructions herein, download and install vim:

sudo apt-get install -y vim

Install Grails 2.x

This step will install Grails and Groovy - https://grails.org/download.html - also see http://grails.org/doc/latest/guide/gettingStarted.html

We will use the SDKman installer. In the following, set grails 2.3.11 as the default; set groovy 2.4.5 as the default. These can be changed with sdk use <tool> <version>, for example sdk use grails 2.3.11 .

curl -s get.sdkman.io | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install grails 2.3.11
sdk install groovy 2.4.5 

Install Tomcat

You will need a framework in which to run the transmart war files. Most exploratory installs use Tomcat7 (the latest version should work fine). 

sudo apt-get install -y tomcat7 

This install will also start tomcat, but we need to shut it down for now; we will start it later in this process.

sudo service tomcat7 stop

NOTE: There is a problem that occurs when the tranSMART webapp runs in tomcat7 (as it is, initially, installed), the application causes Tomcat to run out of Java Heap Space. The work-around, for now, is to edit the file that sets the default parameters for tomcat. Use an editor, with sudo, to edit the file /etc/default/tomcat7. Find the line that set the JAVA_OPTS system variable and change it to read:

JAVA_OPTS="-Djava.awt.headless=true -Xms512m -Xmx2g -XX:+UseConcMarkSweepGC"

Specifically, using vim, enter the command to start vim editing the file and follow the VIM directives given below (<R> indicated the RETURN key)

sudo cp /etc/default/tomcat7 /etc/default/tomcat7-backup
sudo vim /etc/default/tomcat7

(In vim, you can type :q! at any time to quite without saving your changes.)

Once in vim,

• type the single character 'i'  which puts you into input mode (the characters - -  Insert - - appear at the bottom left of the terminal screen).
• Then use the arrow keys to scroll to the line with JAVA_OPTS and edit that line to be the one above (by typing, user the delete and backspace keys, positioning with the arrow keys).
• Then type the single character <ecs> (the Escape-key) to get out of input mode. 
• Double-check your work. 
• And then, type ZZ to save the file and quit.

Install R and Rserve

To install R and Rserve type the following (this will take several minutes):

cd ~/transmart/transmart-data
. ./vars
make -C R install_packages

NOTE: There is a problem with the fact that R, as installed above, is not on the PATH System variable. The following three commands are work-around to fix this problem.Eventually, it will have to be fixed in the scripts. These commands add the path for R to the PATH variable (for all processes); this is done by creating an (new) file Rpath.sh and adding it to the /etc/profile.d/ directory.

cd ~
echo "export PATH=${HOME}/transmart/transmart-data/R/root/bin:$PATH" > Rpath.sh
sudo mv Rpath.sh /etc/profile.d/

This change will take place when you next start the machine, login, or start a new terminal window or shell. To have them take effect immediately you must:

source /etc/profile.d/Rpath.sh

Check and make sure that you have the correct version of R on your PATH:

 R --version

The version number should be 3.1.2 .

Install SOLR

SOLR is a search engine that uses Lucene to built fast searches. In our case, it is build on top of Hibernate so that each search targets a pseudo-tables generated by a data-base query. It is used in multiple places in tranSMART.

In these instructions it is installed as a stand-alone web application. See the documentation for a full explanation of other ways in which it can be installed.

Install SOLR by using the transmart-data command line 'make' file:

cd ~/transmart/transmart-data
. ./vars
make -C solr start

For evidence that it is finished loading, look for the line:

INFO org.eclipse.jetty.server.AbstractConnector – Started SocketConnector@0.0.0.0:8983 

And once it is running, which takes a few minutes, kill it with control-C. You can ignore the resulting error message.

We will restart it, again, later in these instructions.

The tranSMART Web Application

Set up basic database that supports login and contains one study. Set up the configuration file. Set up the war files. Start Rserve, SOLR, and Tomcat.

Setting up a new database and sample data

We use the make files in transmart-data to create a new database and add a sample dataset to the database, GSE8581.

cd ~/transmart/transmart-data
. ./vars
make -j4 postgres
make update_datasets
make -C samples/postgres load_clinical_GSE8581
make -C samples/postgres load_ref_annotation_GSE8581
make -C samples/postgres load_expression_GSE8581

Create the tranSMART Configuration Files

To create the configuration files for the tranSMART web application and the connection to the database:

cd ~/transmart/transmart-data
. ./vars
make -C config install

Unfortunately, these instructions set up the configuration files in the configuration directory for the user transmart in the directory /home/transmart/.grails/transmartConfig, but they need instead to to be in the configuration directory of the user tomcat7 which is in the directory /usr/share/tomcat7/.grails/transmartConfig. So, we copy them

sudo mkdir -p /usr/share/tomcat7/.grails/transmartConfig/
sudo cp /home/transmart/.grails/transmartConfig/*.groovy /usr/share/tomcat7/.grails/transmartConfig/

Setting Up The Web Application

From the transmart-library web site, http://75.124.74.64/wars, download the application's war files: transmart.v1.2.4.war and gwava.v1.2.4.war. We will copy then to a staging directory at ~/transmart/war-files . And then, install then in tomcat's webapps directory as transmart.war and gwava.war. Specifically,

cd ~/transmart
mkdir war-files
cd war-files
curl http://75.124.74.64/wars/transmart.V1.2.4.war --output transmart.war
curl http://75.124.74.64/wars/gwava.V1.2.4.war --output gwava.war
sudo cp *.war /var/lib/tomcat7/webapps/

Running SOLR, Rserve, and Tomcat

These instructions will need to be run (checked) each time you start up. 

SOLR

Check to see that SOLR is running with:

ps aux | grep run.jar 

If is is not, start it with

cd ~/transmart/transmart-data
. ./vars
make -C solr start > ~/transmart/transmart-data/solr.log 2>&1 & 

This last statement rebuilds all the indexes (should be done after each database load; and with SOLR running as above)

 make -C solr rwg_full_import sample_full_import

Rserve

Check to see that Rserve is running with:

 ps aux | grep Rserve

If is is not, start it with

cd ~/transmart/transmart-data
sudo -u tomcat7 bash -c 'source vars; make -C R start_Rserve' 

NOTE: Rserve must be running under the user tomcat7; as above.

Tomcat

Check to see that Tomcat7 is running with:

 sudo service tomcat7 status

If is is running, restart it with

 sudo service tomcat7 restart

If is is not, start it with

 sudo service tomcat7 start

Using the Web Application

Browse to http://localhost:8080/transmart ; log in with username = admin, password = admin ; click on the Analysis tab.

You should see one study "GSE8581".

Drag it to the selection box and click on "Summary Statistics": this will show a summary of statistics for that study.

In this case, transmart is up and running. 

Notes on PostgreSQL 9.3

ls /var/lib/postgresql/tablespaces

sudo service postgresql start
sudo service postgresql stop
sudo service postgresql status