Earlier, I blogged about how to set up a tranSMARTdevelopment environment - this was the GPL 1.0 release which has Oracle as a prerequisite. Nowadays, we have a version that runs on Postgres - it still has some problems, but it is promoted as the current master version.
Recently we had a tranSMART hackathon at Imperial College, organized by Yike Guo c.s. and the eTRIKS project. I was invited to chair this session, even though I am not formally part of eTRIKS, which is just awesome - note how open source community building is not only preached but also practiced by eTRIKS here!
However, at this workshop I found out that many developers who are willing to have a look at tranSMART, are struggling to even get it installed locally. That is a very bad situation, because the entry barrier to the open source community / code should be as low as possible, and I am sure that for many developers, getting it installed and running locally is just the first step to do to get a feeling of what tranSMART is.
So in this blog post, I would like to walk through the steps of installing a local development environment for the current Postgres-based master branch of tranSMART, using an installer that my colleague Pieter Lukasse wrote. I will use the Mac OS X operating system as an example, but the steps are very similar under Linux and even in Windows.
Decide where you want the stuff
I put all my custom applications in a folder called /app, and throughout this example I will use /app/transmart-dev as a base path.
Getting the prerequisites
The README specifies that we have to install a JDK, Git, PostgreSQL, Ant and Grails. Ant is already installed by default on OS X, so is a Java JDK. If you are not using a package manager for OSX yet, I would recommend homebrew - it's easy to use, flexible, and installs all tools in /usr/local. Using homebrew, we can easily install the other tools:
brew install git postgresql grails
If this is really the first time you install PostgreSQL, then follow the instructions homebrew displays for initializing the database with initdb, and restarting postgresql.
Finally, be sure to set JAVA_HOME, for example in your ~/.profile file. Also, I would recommend setting your JAVA_OPTS and GRAILS_HOME there. My ~/.profile looks like this:
export JAVA_HOME=/Library/Java/Home
export GRAILS_HOME=/app/grails
export JAVA_OPTS="-Xms256m -Xmx1280m -XX:MaxPermSize=850m -XX:MaxHeapFreeRatio=70 -XX:MaxGCPauseMillis=10 -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled"
export PATH=$JAVA_HOME/bin:$GRAILS_HOME/bin:/usr/local/share/python:$PATH
You can check where javac is located by issuing ls -al `which javac`, it's probably a symlink to some other symlink. I also use /app/grails as a symlink to the current latest Grails version installed by homebrew.
Downloading and configuring the installer
Now, you are ready to run the installer. Check it out with git:git checkout https://github.com/thehyve/transmartAppInstaller.git /app/transmart-dev/installer
The next step is to configure the installer using a file called setupTranSMARTDevelopment.properties. We will use the Mac OSX template as a starting point:
cd /app/transmart/installer/scripts
rm setupTranSMARTDevelopment.properties
cp setupTranSMARTDevelopment.properties.mac setupTranSMARTDevelopment.properties
Now, edit this file and configure the properties to match your environment. If you followed these instructions, most properties can actually stay at their defaults. The final step is then to execute the installer. Just to be sure, only do this when you have not yet installed tranSMART yet, because otherwise it will clean and overwrite your current setup.
./startup.sh
This will take a while (can amount to over 2 hours!)
When the installer is finished, you will have the major prerequisites for developing with the Postgres version of tranSMART. So the final step is to checkout the project itself, for example in /app/transmart/app:
git checkout https://github.com/transmart/transmartApp.git /app/transmart-dev/app
cd /app/transmart-dev/app
grails compile
Now you can start your local transmart instance by running i2b2 and tranSMART. One way to do this is opening 2 terminal windows, so you can monitor the output of both tools. These are the commands to run both tools:
cd /app/transmart/jboss
bin/run.sh
cd /app/transmart/app
grails run-app
When both tools are up and running, you should be able to browse your local tranSMART instance at http://localhost:8080/transmart. The next step if that works in then to install at least R and run Rserve, so that you can do some analyses, set up the ETL environment so that you can import your own data, install Solr to get the Search Explorer going, and install PLINK and GenePattern for some omics analyses. But that's for some other posts.
Finally a word of advice, something I regret not giving during the hackathon because people ran into all kinds of problems with SpringSource STS - if you consider using an IDE to run the tranSMART application, I would highly recommend IntelliJ IDEA Ultimate Edition. You can get a free license for it if you work on open source projects (as is the case with tranSMART). It escapes me how the folks at SpringSource can write great tools like Grails and at the same time come up with an IDE as buggy, slow and hard to configure as SpringSource STS. I have tried it several times and never even got it to run a Grails project correctly. It's a personal experience, but I'm definitely not the only Grails developer who feels this way.
Of course tranSMART is very much work in progress, in a few days we might not even need the i2b2 binaries anymore as my colleague Gustavo is working, as per our involvement in the CTMM TraIT project, on factoring out the calls to i2b2 to a lean tranSMART Core API and implementing the few calls that were still routed to the i2b2 ONT and CRC cells to a tranSMART implementation. The rationale of this is that the i2b2 schema's are used all over the tranSMART code anyway, so it doesn't make too much sense to still depend on the whole i2b2 codebase for these few calls. But again the full story is food for another post.
