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

This outline is the overview of the install process. 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 machines memory).

1. You will need the set up the necessary support tools (Basics, PostgreSQL, Grails, Tomcat, R, RServe, and SOLR).
2. You will need to set the database. 
3. 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, to perform analysis.

There is a Sanity Checklist for a fully functional system, to make sure that everything was correctly installed and it running properly.

Hardware Requirements

The requirements vary based on  your specific needs.  As an example, if you have no more than 20 subjects, a couple of studies with genomic data, and less than 10 users, you can combine the app server with the database server into a single VM or a standalone server with the following specs:

• CPU: Dual core or more
• Memory: 4 to 8GB (8 preferred)
• Storage: 50 GB
• OS: linux (these instructions assume: Ubuntu 14.04).
• Database:  Postgres 9.3 or later.

Installing Support Tools

These instructions are based on the assumption that you are installing tranSMART version 1.2.4.

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!

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, name = transmart, password = transmart. Obviously, these can be changed later.

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 all the tools required. To use it, do the following:

• In a Browser Download https://github.com/tranSMART-Foundation/transmart-data/archive/release-1.2.4.zip

• Create a folder, transmart, to contain the app, mv the download zip file (transmart-data-release-1.2.4.zip) to that folder and unzip it.
• In the folder, transmart, rename transmart-data-release-1.2.4 to transmart-data and cd to that folder.

• The relevant instructions are in the README.md file, but repeated here for completeness:

  sudo make -C env ubuntu_deps_root
  make -C env ubuntu_deps_regular

Install Ant - http://ant.apache.org/manual/install.html#installing ; install Maven - http://maven.apache.org/download.cgi#Installation ; i

sudo apt-get install -y ant
sudo apt-get install -y maven

NOTE: There is an error in the install of groovy that needs to be fixed in the install 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

Install Grails 2.x

How to install Grails - https://grails.org/download.html - also see http://grails.org/doc/latest/guide/gettingStarted.html

We will use the SDKman installer. 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

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

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 -Xmx1024m -XX:+UseConcMarkSweepGC"

Install R and Rserve

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

NOTE: the following three commands are work-around (to fix a problem with the PATH environment variable) and will have to be fixed in the scripts. They are need to set the PATH variable (for all processes) to pick up the this version of R on the path.

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.

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

The tranSMART Web Application

Set up basic database that supports login and 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 fines in transmart-data to create a new database and add data to it.

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 loading data into transmart:

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

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

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 &
make -C solr rwg_full_import sample_full_import

This last statement rebuilds all the indexes (should be done after each database load)

Rserve

Check to see that Rserve is running with:

ps aux | grep Rserve

If is is not, start it with

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

Tomcat

Check to see that Tomcat7 is running with:

sudo service tomcat7 status

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 

     pg_ctl -D /usr/local/var/postgres/ status

     pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start