Welcome to the caTissueSuite Wrapper for ERNE. ERNE stands for the EDRN Resource Network Exchange, a virtual specimen bank that enables member sites of EDRN to share their specimen collections in a uniform way and without impacting their existing specimen catalogs and annotation information. caTissueSuite is a specimen inventory and management system. The caTissueSuite Wrapper for ERNE enables an installation of caTissueSuite to become part of the ERNE network; that is, specimen queries through ERNE can interrogate the specimen inventory managed by a caTissueSuite installation.

This software was developed by and is copyrighted 2010 by the California Institute of Technology. ALL RIGHTS RESERVED. U.S. Government sponsorship acknowledged.


This is a preliminary release intended as a proof-of-concept. It currently handles only one of the ERNE Common Data Elements (CDE), SPECIMEN_COLLECTED_CODE. You can query for SPECIMEN_COLLECTED_CODE = 1 or SPECIMEN_COLLECTED_CODE = 0 and ask for SPECIMEN_COLLECTED_CODE as a return value. You can ask for other return values but they'll be listed as "unknown" in the response. Using other CDEs as constraints will result in errors.

Don't worry, future CDEs should be implemented shortly.

Further, this implementation solely supports HTTP. HTTPS should come in a future release.

Quick Install

Crave adrenaline and hate reading? Don't bother with the rest of this README, just adapt the following procedure to your environment:

% python -V
Python 2.4.x
% java -version
java version "1.5.x_xx"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.x_xx-xxx)
Java HotSpot(TM) Client VM (build 1.5.x_xx-xxx, mixed mode, sharing)
% ant -version
Apache Ant version 1.7.1 compiled on XXX xx xxxx
% tar xjf caTissueWrapper-x.x.x.tbz
% cd caTissueWrapper-x.x.x
% vi operations.cfg
% python bootstrap.py -dc operations.cfg
% bin/buildout -c operations.cfg
% bin/supervisord
% echo Miller time
Miller time

Not working? Read the rest of the document for assistance.


The caTissueSuite Wrapper for ERNE makes several assumptions about the host platform on which it will run and has needs several prerequisite software packages already installed in order to operate. In summary, these requirements are:

  • A Unix-like system

  • Python >= 2.4 but < 3

  • Java Development Kit 1.5 or 1.6

  • Ant >= 1.7

  • Active connection to the public internet

  • A caTissueSuite server running with:
    • Its hostname and port number
    • Account name and password that can access its remote services
  • Approximately 830 MiB of free disk space.

These requirements are detailed in the subsections that follow.


We've tested the caTissueSuite Wrapper for ERNE on a number of platforms, including:

  • Mac OS X 10.6 "Snow Leopard", with the Xcode software development kit
  • Debian GNU/Linux 5.0.3 "Lenny"

Other Unix systems will likely work just fine. Windows systems are not supported at this time. Make sure your Unix-like system can resolve hostnames, including its own. The target volume will need about 830 megabytes of free space for the installation.


The caTissueSuite Wrapper bootstraps and builds itself using the Python programming language. Python is usually pre-installed on most Unix systems. Any version from 2.4 onward but not 3 or later should work just fine, such as versions 2.4, 2.5, 2.6, and 2.7. You won't need the development installation of Python; the runtime-only is fine.

To see if you have the runtime, run python -V. You should see output similar to Python 2.6.1.

If you don't have Python, you may wish to install from the Python source or investigate your platform-specific installers.


The caTissueSuite Wrapper requires the Java Development Kit (JDK). We've tested the wrapper with the following JDKs:

  • Java 1.6 provided with Mac OS X 10.6
  • Java 1.5 installed through sun-java5-jdk on Debian GNU/Linux 5.0.3

Run java -version to see what version (if any) is available on your system. Check your operating system instructions for installing Java.


The caTissueSuite Wrapper needs the Ant build tool to construct its Java-based runtime environment out of caTissueSuite and other libraries. We've tested the Wrapper with Ant version 1.7, but later versions ought to work just fine, too.

Run ant -version to see what version (if any) is available on your system. Your operating system may provide a package to install Ant or you can install a binary from the Ant website.

Internet Connection

The caTissueSuite Wrapper for ERNE is deployed using Buildout. Buildout automates the retrieval and compilation of the components that comprise the wrapper as well as configuration of those components. Therefore, you'll need an active internet connection to complete the installation.


To install the caTissueSuite Wrapper, first ensure the target system meets the requirements in the above section. Then, follow the steps describes in this section, below. Installation is largely automatic and requires only a few hand-typed commands.

  1. Extract the archive.
  2. Configure it.
  3. Bootstrap the buildout.
  4. Build it out.
  5. Start the supervisor.
  6. Make it run at boot-up.

You'll need root privileges for the final step.

Extracting the Archive

To extract the archive:

  1. Pick a directory where the Wrapper and all of its supporting files will live, such as /usr/local, /opt, /var, etc. You can use a subdirectory of your home directory, if you wish. You could create a new user ID and use its directory. The Wrapper does not require any special privileges. Change the current working directory to the target directory.

  2. Decompress and extract the archive. Depending on your operating system, and of the following commands should work:

    tar xjf caTissueWrapper-x.x.x.tar.bz2
    gtar xjf caTissueWrapper-x.x.x.tar.bz2
    bzip2 -c caTissueWrapper-x.x.x.tar.bz2 | tar xf -
  3. Change the current working directory to the newly extracted caTissueWrapper-x.x.x directory.

Configuring the Wrapper

To configure the wrapper, edit the operations.cfg file and make the following adjustments as needed:

  1. In the [interfaces] section:
    • Set the hostname or IP address of the JBoss server where your caTissueSuite is running.
    • Set the hostname or IP address of the network interface where ERNE should be available (you can leave this blank to specify that ERNE should bind to all available network interfaces).
    • Set the hostname or IP address of the network interface where you would like the Supervisor process monitor to be available.
  2. In the [ports] section:
    • Set the port number of the JBoss server where your caTissueSuite is running.
    • Set the port number where you want ERNE to listen. Most ERNE sites choose port 7576. You're free to pick any port number. Note that to be a part of ERNE this TCP port must be available on the public internet; adjust your firewall if necessary.
    • Set the port number where you want the Supervisor process monitor to listen.
  3. In the [users] section:
    • Set the user name (in the form of an email address) for an account that can access the caTissueSuite remote service.
    • Set a user name to protect access to the Supervisor.
  4. In the [passwords] section:
    • Set the password of the caTissueSuite user name.
    • Set a password to protect access to the Supervisor.

Save changes to the operations.cfg file.

Bootstrapping the Buildout

The Wrapper uses the Buildout system to construct, configure, and deploy itself. You don't need to download Buildout, though. A bootstrapping file is included that takes care of that.

To bootstrap, run:

python bootstrap.py -dc operations.cfg

Building the Wrapper

Once bootstrapped, you can build the wrapper by running:

bin/buildout -c operations.cfg

This step may take quite some time as several large software packages must be downloaded, configured, and compiled. If you're fond of coffee, now would be an opportune time to procure a cup.

Starting the Supervisor

The Wrapper uses the Supervisor process monitor. Supervisor provides a convenient, attractive web interface (at the host and port you configured in operations.cfg) that lets you check on the status of monitored processes, start and stop processes, and so forth. (You can also use the command bin/supervisorctl to interact with the Supervisor.)

To start the Supervisor, which in turn starts the Wrapper, run:


You can then visit the Supervisor web interface with a browser or run bin/supervisorctl status to check on processes, or run bin/supervisorctl by itself to enter an interactive session (type help for help).

If you need to re-do any of the installation steps, shutdown the Supervisor by running:

bin/supervisorctl shutdown

Avoiding the Supervisor

If your site already has a process monitoring system, you can skip Supervisor. Just run bin/start.sh to run the Wrapper. Kill the process to stop it.

Post-Deployment Configuration

The Wrapper requires no post-deployment configuration save to ensure that it runs at boot-up time so that it's always available to the entire ERNE network.

Notice: Don't bother with this yet until the Wrapper is stable, supports all CDEs, and runs with HTTPS.

How you do so depends on your operating system. You may need to:

  • Create a SysV-style init script in /etc/init.d that calls bin/supervisord to start and bin/supervisorctl shutdown to stop
  • Add execution of bin/supervisord to /etc/rc.local
  • Add bin/supervisord to the @reboot event of root's crontab
  • Something even more exotic

Consult your operating system documentation for details.

Questions, Bug Reports, and Help

For feedback about this product, please visit the feedback page at http://cancer.jpl.nasa.gov/contact-info.