
Original version: February 5, 2008
Revision A: March 19, 2009
Revision B: September 9, 2009
Revision C: November 4, 2009
Revision D: December 3, 2009
Revision E: November 17, 2010
Revision F: November 24, 2010
Revision G: February 02, 2011
Revision H: December 11, 2012

------------------------------------------------------------------------------
Deploying a BioTapestry Viewer

After a few customizations, the files in this ZIP archive can
be installed on your web server to host a BioTapestry Viewer.

0) FIRST STEP!

IMPORTANT: The web server must be configured to correctly handle files
with the ".jnlp" suffix.  Some web servers are already set up to do
this, but others need to be tweaked.  The core issue is that the
web server needs to understand that when it serves up a file
with a ".jnlp" suffix, it tells the web browser that the
incoming file has the MIME type of "application/x-java-jnlp-file".
With that information, the web browser will know that it needs
to fire up Java WebStart to handle the file.  Otherwise, it will
just show up as plain text in the browser.

If you are administering the web server yourself, you need to
make changes as outlined below.  If you do not have administrator
permissions on your web server, you need to ask your systems
administrator to make these changes for you.

For the Apache server, the "mime.types" file needs to have a line 
added if it is not already there.  The line is:

application/x-java-jnlp-file	jnlp

(that's a TAB before the "jnlp", though spaces seem to work OK too...)

The mime.types file is frequently in the Apache configuration (conf)
directory.  If not, check the main httpd.conf file in the configuration
directory and look for a line like this to find where mime.types is:

TypesConfig /etc/mime.types

Once the change has been made, the web server must be RESTARTED
for the change to take effect!

On Windows IIS servers, ask the site administrator what steps
need to be taken. 

I) BUNDLE UP YOUR .btp FILE

1) Create a .jar file containing your .btp file.  You will need the
Java SE Development Kit (JDK), which can be downloaded from
Sun at http://java.sun.com/.  This kit contains the jar 
utility.  Typically, the .btp file is placed in a subdirectory
with a path that matches your internet domain name.

The following example uses a bash shell on Linux.  The ">"
symbol represents the command prompt.  Using a
command shell on Windows should work in a similar fashion,
with slightly different command syntax for creating directories,
copying files, etc.

a) Say your .btp file is in your ~/tmp directory, e.g.

> ls ~/tmp
SpEndomes.btp

b) Create an empty working directory:

> cd ~
> mkdir -p tmp/working

c) Go to the working directory:

> cd tmp/working

d) Create a directory structure in the working
directory that mimics *your* internet domain 
path, plus a "data" subdirectory at the end, e.g.:

> mkdir -p org/biotapestry/data

e) Place your .btp file in that directory:

> cp ~/tmp/SpEndomes.btp org/biotapestry/data

f) Check that you have what you want.  A single data file
sitting in the bottom subdirectory:

> ls ~/tmp/working/org/biotapestry/data/
SpEndomes.btp

g) Make sure you are in the working directory:

> cd tmp/working
> ls
org

h) Run the jar command:

> jar cvf ViewerDataFile.jar org
added manifest
adding: org/(in = 0) (out= 0)(stored 0%)
adding: org/biotapestry/(in = 0) (out= 0)(stored 0%)
adding: org/biotapestry/data/(in = 0) (out= 0)(stored 0%)
adding: org/biotapestry/data/SpEndomes.btp(in = 1502607) (out= 72530)(deflated 95%)

i) You now have a jar file called ViewerDataFile.jar that will
be placed on your web server.

II) BUILD AN INDEX.HTML FILE STARTING WITH THE BUNDLED EXAMPLE:

The bundled index.html file can be used as a starting point for your
launch page.  It contains a very simple launch link, which has a
downside: if Java is not installed on the user's machine, they 
will either get a page of text (the .jnlp file contents) or
a question if they want to save the file to disk or run it with some
selected program.  Note the bundled .jnlp file contains a text block
that tries to warn the user about this if they end up viewing the file.

There are more sophisticated ways to handle this problem.  For example,
this link fron Sun describes a way to deploy web apps (deployJava.js); see: 

http://java.sun.com/javase/6/docs/technotes/guides/jweb/deployment_advice.html

The problem is that over the years, attempts to be "smart" about
this issue have frequently broken down, and need to be fixed.  In
the interest of not having to service all the Viewer installations
when issues arise, this distribution only offers the simple appraoch. 

III) CREATE A DIRECTORY ON YOUR WEB SERVER

Where this gets created depends on your web server installation.  In this
example, let's say that the URL http://www.biotapestry.org/viewerDemo/index.html
serves up the web page from the file: /html/viewerDemo/index.html.

a) Go to the target directory:

> cd /html/viewerDemo

b) Copy the index.html file you created in (II) above into the 
target directory: 

> cp [directory where your edited file lives]/index.html .

c) Copy the data jar file you created in (I) above into the 
target directory: 

> cp [directory your bundled data file lives]/ViewerDataFile.jar .

d) Copy the BioTapestry program .jar file from the zip distribution into 
the target directory: 

> cp [directory you created by unzipping]/bioTapestryViewer.6.0.0.jar .

e) Create a webStart subdirectory of the target:

> mkdir webStart

f) Copy the files from the webStart directory in the viewer zip distribution
into the webStart subdirectory:

> cp [directory you created by unzipping]/webStart/bioTapestry.jnlp webStart
> cp [directory you created by unzipping]/webStart/BioTapFabIconWhite.gif webStart 

IV) CUSTOMIZE THE JNLP FILE

You now need to edit the bioTapestry.jnlp file you copied to the webStart
subdirectory for the specifics of your web site.  Bring up the bioTapestry.jnlp
file in a text editor (e.g. WordPad, NOT Word), and make the following changes: 

a) The codebase needs to be customized to your site.  The following line:

     codebase="http://YOUR_WEB_SERVER/PATH_TO_BIOTAPESTRY_VIEWER_LINK_PAGE_DIRECTORY/"
 
needs to be changed to (using the URL from part III of our current example; change 
this to the URL you are using that contains your index.html file):

     codebase="http://www.BioTapestry.org/viewerDemo/"

b) The jar file you created in part I needs to be specified.  In this example, we 
used the name ViewerDataFile.jar, so this line:

    <jar href="YOUR_BTP_FILE_IN_A_JAR.jar"/>

is edited to read like this:

   <jar href="ViewerDataFile.jar"/>

c) The location of the .btp file inside the jar file needs to be specified.  From this
example, we would change this line: 

  <argument>/PATH_TO_YOUR_FILE_INSIDE_JAR/YOUR_BTP_FILE.btp</argument>

to this (note the leading slash):

 <argument>/org/biotapestry/data/SpEndomes.btp</argument>

d) Save the bioTapestry.jnlp file.

V) TEST THE INSTALLATION

To review, your web site should contain the following files:

index.html (an expanded version of the bundled index.html)
bioTapestryViewer.6.0.0.jar (from the distribution)
ViewerDataFile.jar (or whatever you called it - contains your .btp file)
webStart/bioTapestry.jnlp (edited to contain customized entries)
webStart/BioTapFabIconWhite.gif (from the distribution)

Go to the home page (e.g. http://www.BioTapestry.org/viewerDemo/index.html in
this example) and lick on the link to launch the Viewer.  If you just get the 
jnlp file as plain text (assuming you have Java installed on your computer)
make sure that the web server has been configured as in "step 0".

If you have problems, check that the installation matches the above instructions.
If you still have problems, contact us at biotapestry -at- systemsbiology -dot- org,
or post to the BioTapestry-Users Google group.

VI) LET US KNOW YOU ARE USING THE VIEWER

We'd like to link to your viewer page off the BioTapestry home page.  Even
if you prefer not the be linked to, we appreciate keeping track of viewer
deployments.  Thanks!

