TranSMART Installation (The Hyve)

This installation manual is meant to be a guide for people who want to install tranSMART with the smallest number of manual steps.

Please note: these instruction are based on resources downloaded from theHyve.

If you want to see more technical details or perhaps develop on transmart the tranSMART 1.2 INSTALLATION NOTES ON UBUNTU should be used instead.

This document contains instructions for installing TranSMART for two major types of Linux OSs: debian-based and rpm-based.

It's tested against Ubuntu 14.04 (deb). But should work for other versions as well perhaps with small modifications.

Installation particularities for Oracle and PostgreSQL are specified. Oracle DBMS installation is out of scope of this document.

NOTE: Linux user that is used for installation should be able to run commands on behalf of root user (sudo).

NOTE: So far this installation manual would work for both TranSMART versions 1.1 and 1.2. It's just matter of which transmart-data and transmart web application you would choose (steps 3 and 9 respectively).

If you have any questions or difficulties with installation please do not hesitate to ask. The best ways to get answers are by using hipchat or tranSMART google groups.

Here is a link for registering with hipchat. Use transmart-release group when you are in hipchat.

Step 1

Add The Hyve package repository.

NOTE: There are just amd64 builds. There are no 32-bit system packages.

Ubuntu

CentOS

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 3375DA21
echo deb http://apt.thehyve.net/internal/ trusty main | \
  sudo tee /etc/apt/sources.list.d/hyve_internal.list
sudo apt-get update

sudo tee /etc/yum.repos.d/thehyve_internal.repo <<EOD
[thehyve_internal]
gpgcheck=0
baseurl=https://repo.thehyve.nl/content/repositories/releases
enabled=1
name=The Hyve Internal RPM releases
EOD

# for PostgreSQL only
sudo yum localinstall \
http://yum.postgresql.org/9.3/redhat/rhel-6-x86_64/pgdg-redhat93-9.3-1.noarch.rpm

Step 2

Install all prerequisites that could be found in the package repositories

Ubuntu CentOS

PostgreSQL

sudo apt-get install -y \
make					\
curl					\
git						\
			openjdk-7-jdk			\
groovy					\
php5-cli				\
php5-json				\
postgresql-9.3			\
apache2					\
tomcat7					\
libtcnative-1           \
transmart-r

Alternatively you could install just git.

And later when transmart-data will be installed all other dependencies with:

sudo make -C env ubuntu_deps_root

sudo yum install -y \
make                \
curl                \
git                 \
java-1.7.0-openjdk  \
groovy              \
php55-cli-minimal   \
postgresql93        \
httpd               \
transmart-r

NOTE: For CentOS 7, the official PHP packages can be used.

NOTE: For CentOS 7, due to upstart not being used anymore, replace transmart-r with transmart-r-systemd.

NOTE: Using the official tomcat6 package in CentOS 6 is not recommended. Download the upstream binaries instead. See Tomcat 7 manual installation guide for instructions. You will then have either to 1) compile libtcnative to enable the APR connector or 2) enable the NIO connector.

Oracle

Exclude postgresql-9.3 from list of packages above.

Exclude postgresql93 from list of packages above.

Step 3

Get transmart-data. Please read readme before. Especially look into requirements.

cd ~
git clone https://github.com/transmart/transmart-data.git
cd transmart-data

Step 4

Configure transmart-data

Ubuntu CentOS

PostgreSQL

php env/vars-ubuntu.php > vars

cp vars.sample vars

You should change vars content according with your environment. Here is example with frequently changed variables.

NOTE: Kitchen tool and kettle ETL scripts (KETTLE_JOBS_PSQL) will be installed later in step 9.

PGSQL_BIN=/usr/bin/
TABLESPACES=/var/lib/pgsql/tablespaces/
KETTLE_JOBS_PSQL=$HOME/transmart-data/env/tranSMART-ETL/Postgres/GPL-1.0/Kettle/Kettle-ETL/
KITCHEN=$HOME/transmart-data/env/data-integration/kitchen.sh

Oracle

cp vars.sample vars

NOTE: You need to change oracle variables (usually starts with ORA or ends with _ORA) according with your oracle db settings. Do not forget to export ORACLE=1. It's important for solr and make config.

Read configuration settings to current environment.

source vars

Step 5

Create transmart database table-spaces and schema

PostgreSQL	sudo -u postgres bash -c "source vars; PGSQL_BIN=/usr/bin/ PGDATABASE=template1 make -C ddl/postgres/GLOBAL tablespaces" make postgres
Oracle	make oracle

Step 6

Copy tranSMART configuration files

PostgreSQL/Oracle	sudo bash -c "source vars; TSUSER_HOME=~tomcat7/ make -C config/ install" Replace `tomcat7` with the user tranSMART is to run under.

Step 7

Install and run solr

There are many ways in which Solr can be run. For production usage it should be installed as a system service. One way to do that is to configure it as a tomcat web app, which will be shown here. The default Transmart configuration expects Solr to be running on http://localhost:8080/solr. Note that the solr/solr directory needs to be writable by the Solr process, this is where the indexes will be stored.

A simpler way to start solr without installing it as a service is to do the following, but for production use this is not adequate. This will run Solr on port 8983, so you need to change that in the Transmart configuration.

nohup make -C solr/ start &

To install Solr as a Tomcat 7 web app:

Ubuntu CentOS

PostgreSQL/Oracle

make -C solr solr_home
sudo chown -R tomcat7 solr/solr
TS_DATA=`pwd`
sudo -u tomcat7 tee /etc/tomcat7/Catalina/localhost/solr.xml <<EOD
<?xml version="1.0" encoding="utf-8"?>
<Context docBase="$TS_DATA/solr/webapps/solr.war" crossContext="true">
  <Environment name="solr/home" type="java.lang.String" value="$TS_DATA/solr/solr" override="true"/>
</Context>
EOD

Solr needs some additional libraries, but they need to be placed in Tomcat's webapps/solr/WEB-INF/ directory, which is only created when Solr is deployed. So start Tomcat for a moment so it deploys Solr:

sudo service tomcat7 start
sudo tail -f /var/log/tomcat7/catalina.out
# ... lots of output, Solr fails to start ...
# When Tomcat has started up, press Ctrl-C to return to the shell
sudo service tomcat7 stop

Copy the missing Solr libraries to the now created webapps/solr folder:

TS_DATA=`pwd`
WEBINF=/var/lib/tomcat7/webapps/solr/WEB-INF/
for f in $TS_DATA/solr/lib/ext/*
do
	sudo -u tomcat7 cp $f $WEBINF/lib/
done
sudo -u tomcat7 mkdir $WEBINF/classes
sudo -u tomcat7 cp $TS_DATA/solr/resources/log4j.properties $WEBINF/classes

Optionally, start Tomcat again to verify that Solr now starts up correctly. Solr should become accessible at http://localhost:8080/solr.

Run the same steps as for Ubuntu. Adjust Tomcat paths and username to what your system uses.

If you installed Tomcat 7 manually into /opt/tomcat7/tomcat/, make the following replacements in your commands:

/etc/tomcat7 -> /opt/tomcat7/tomcat/conf
/var/lib/tomcat7 -> /opt/tomcat7/tomcat
/usr/share/tomcat7 -> /opt/tomcat7/tomcat

To start Tomcat manually, you can use this command instead of the sudo service tomcat7 start:

sudo -u tomcat7 sh -c "cd /opt/tomcat7/tomcat; bin/catalina.sh run"

Then after the startup has finished, press Ctrl-C to shut down Tomcat.

Step 8

Configure and start Rserve.

echo 'USER=tomcat7' | sudo tee /etc/default/rserve
sudo service rserve start
# or on some older systems with upstart: sudo start rserve

On CentOS 6, you will also need to edit /etc/sudoers and remove the line "Defaults requiretty" before rserve will be able to start. Use the command 'sudo visudo' to edit the file.

Step 9

Deploy tranSMART web application on Tomcat.

You need to increase memory setting for tomcat firs.

sudo service tomcat7 stop
# or on some systems with upstart: sudo stop tomcat7
echo 'JAVA_OPTS="-Xmx4096M -XX:MaxPermSize=1024M"' | sudo tee /usr/share/tomcat7/bin/setenv.sh

Last Release. 1.2.x

sudo wget -P /var/lib/tomcat7/webapps/ https://ci.transmartfoundation.org/browse/DEPLOY-TRAPP/latestSuccessful/artifact/shared/transmart.war/transmart.war

If you installed Tomcat manually, replace /var/lib/tomcat7 with the path to your Tomcat installation.

Latest Development Version. 1.2.x

sudo wget -P /var/lib/tomcat7/webapps/ https://ci.transmartfoundation.org/browse/SAND-TRAPP/latestSuccessful/artifact/shared/transmart.war/transmart.war

If you installed Tomcat manually, replace /var/lib/tomcat7 with the path to your Tomcat installation.

sudo service tomcat7 start
# or on some systems using upstart: sudo start tomcat7

Step 10

Prepare ETL environment

make -C env/ data-integration
make -C env/ update_etl   # or update_etl_git for newer transmart versions, not recommended for production use.

Step 11

Upload example studies. In this example we upload different data types for study with name GSE8581.

You could get more study names and their data types by going with this link http://75.124.74.46:40080/datasets/datasets_index

PostgreSQL

make -C samples/postgres load_clinical_GSE8581
make -C samples/postgres load_ref_annotation_GSE8581
make -C samples/postgres load_expression_GSE8581

Oracle

make -C samples/oracle load_clinical_GSE8581
make -C samples/oracle load_ref_annotation_GSE8581
make -C samples/oracle load_expression_GSE8581

That's it. You should be able to go to http://localhost:8080/transmart/. Use admin as login and admin as password.

Space shortcuts

Child pages

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

Step 7

Step 8

Step 9

Step 10

Step 11