Workarounds to Install and Run a GenePattern Server on Mac OS X 10.9 Mavericks

Posted on Wednesday, May 07, 2014 at 05:49PM by David Eby

In a previous blog post we gave some limited instructions for using GenePattern with Mac OS X 10.9 Mavericks.  While accessing the public server via web browser is not an issue, installing and running your own GenePattern server is a different matter.  Issues with the installer, server launcher, and general responsiveness prevent us from officially supporting this platform right now.  We are actively working to address these problems and expect to have a fix in a future version of GenePattern, as soon as is feasibly possible.  This is very important to us and is on our immediate agenda.

In the meanwhile, however, we have some new workaround recommendations which should improve your current experience running the GenePattern server on Mavericks.

I'll start off by explaining how to launch GenePattern server for the benefit of those folks who had it installed and working on an earlier version of OS X but then upgraded to Mavericks and ran into the responsiveness issues.  We recommend the installer workaround for only advanced - and highly dedicated - users, so I'll set that aside for the moment; those instructions follow afterward.

Running GenePattern Server

We have found that the GenePattern server is much more responsive on Mavericks when launched from a Terminal.app command line.  We have not done extensive testing but our general impression is that the GenePattern server performs at least as well as it did on previous versions of OS X when launched this way.  While doing so is not as simple as using the Start/Stop icons, it is still reasonably easy if you already have Java 6 installed (see below for Java 7 instructions).  Just open Terminal.app (found in Applications>Utilities) and issue the following commands:

cd /Applications/GenePatternServer/Tomcat/
nohup bin/catalina.sh run &

You will need to execute those two commands every time you want to launch the GenePattern server. The first 'cd' step is very important: Tomcat will not launch properly if you try to start it while in a different directory.  The commands above will start the server in the background and capture all logging output to a file named nohup.out in the /Applications/GenePatternServer/Tomcat/ directory.  You can refer to this file later if you need to troubleshoot any issues.  Launching the GenePattern server this way should put a new 'java' icon in your Mac tray.  To stop GenePattern server later, you can just use the usual Quit or Force Quit commands from this icon.  If you'd like to be able to stop GP from the command line instead, use:
cd /Applications/GenePatternServer/Tomcat/
bin/catalina.sh stop
(the 'nohup' command is not necessary)
 
Again, the above commands will only work if you have installed Java 6 from Apple.  Remember that this may have been removed by the Mavericks upgrade; it is available here if you need it.  

Running with Java 7

If you are not able or do not wish to install Java 6 it is possible to use Java 7 instead (available here).  GenePattern server has not been tested extensively under Java 7 and is not yet officially supported, but so far all indications are that it works fine.  Official support is coming in a future release and is also a high priority.  You'll need to set the JAVA_HOME environment variable to point to the Java 7 location before you can launch GenePattern with Java 7 and will require use of the Terminal.app command line.  The following steps assume that you are using the 'bash' shell; modify accordingly for a different shell:
  1. Install Java 7
  2. Open Terminal.app and change to your home directory (using the 'cd' command) if you are not already there.  
  3. Open your .profile file with a text editor such as emacs or vi and add the following line to the file:
    export JAVA_HOME=`/usr/libexec/java_home -v 1.7`
  4. Save this file and quit the editor
  5. Either quit Terminal.app and restart or else load these settings from the command line using:
    source ~/.profile
  6. From the Command line, verify that JAVA_HOME has been properly set using:
    echo $JAVA_HOME
    It should print something like:
    /Library/Java/JavaVirtualMachines/jdk1.7.0_55.jdk/Contents/Home

After this, you should be able to start and stop GenePattern from the Terminal.app command line as described above.

Installing GenePattern on Mavericks

The instructions above assumed that you already had GenePattern installed on your laptop and then went through a Mavericks upgrade.  We wanted to help those users who had already gotten stuck in that situation and are willing to employ the workaround (starting/stopping the GenePattern server from the Terminal.app's command line) in order to keep running GenePattern.  For Mavericks users who have not yet installed a local server, we recommend that you use our public server instead.  As with Java 7, using GenePattern with Mavericks is not yet officially supported and we'd prefer not to encourage other users to reach a point where they need to follow difficult instructions for daily use.  Again, we plan to address this in a future release as soon as is feasibly possible.

Having said all of that, however, it is possible to install GenePattern on Mavericks if you would really must.   Please, just review the previous instructions first and be sure that you are actually willing to take those steps.  Then browse the instructions given below to see if you're comfortable with the process.  If any of this looks too difficult or scary, remember that our public server awaits.

Still with me?  OK, then here we go...

The first thing to know is that our current installer requires Java 6 (available here).  If you are not willing or able to install Java 6, then stop here.  We have future plans to release GenePattern with a new installer that does not have the Java 6 dependency. 

After downloading the installer from our website, if you decompress and try to run it on Mavericks you will get a popup error claiming that the file is damaged:

The file is not actually damaged; this is a Mavericks security measure.  To work around this:

  1. Using Terminal.app (found in Applications>Utilities), navigate to the Downloads directory:
    cd ~/Downloads
  2. Find the GPserver.app directory and navigate to Contents/MacOS:
    cd GPserver.app/Contents/MacOS
  3. Run the installer:
    ./GPserver
    This will start up the installer as usual.
  4. Fill out the installer, being sure to "Allow" the app to accept incoming network connections. 

At the end of the installion prcoess, the GenePattern server will be automatically started behind the scenes.  Note that this may be painfully slow as it is being started by the same mechanism as the StartGenePattern.app icons and suffers the same problems.  I suggest that you go get a coffee, tea, or other beverage of your choice at this point while allowing this to complete.  Hopefully when you return the server will be running.  My recommendation is that you immediately shut down the server before proceeding.  You can use the StopGenePatternServer.app icon but this will also be painfully slow for the same reason.  You can instead stop it from the command line or by using the usual Quit or Force Quit commands.

Restart the server using the instructions in the previous section.  Now it should perform much better, starting up and changing pages far more responsively.

After you have finished installing a Registration screen will appear. This may not succeed:

If that happens to you, add the following line to your <GP_HOME>/resources/genepattern.properties file:
registeredServer=true

Then stop and restart the server as before.  This will skip the registration process when you load the GenePattern main page.  You will need to register a new user before logging in.

From this point on, the server should function normally.

Again, remember that Mavericks is not yet a supported platform for installing GenePattern and has not yet been well tested.  If you have any doubts or concerns then perhaps it would be better to wait for an official release; we are actively working on this.  If you decide to try and run into any problems, please let us know and we will do our best to address them.

Back to Blog