Laika is a Ruby on Rails application that targets JRuby/Glassfish for deployment.

Dependencies

  • JRuby >= 1.4.0

  • Sun Java >= 1.5 (1.6 required for the Glassfish gem)

  • MySQL >= 5.0 (for UMLS)

  • PostgreSQL >= 8.1 (for XDS)

(Laika itself supports either Postgres or MySQL database storage.)

See laika.wiki.sourceforge.net/LaikaXDSPIXPDQAlpha for information about getting an Amazon EC2 system prepared to run Laika.

End-to-end Install Instructions

Once you get a copy of the Laika code from gitHub, these are step-by-step instructions to get Laika installed on your local machine.

Environment

Laika uses Saxon (saxon.sourceforge.net/) to handle XML Schema validation and XSLT. For this to function properly, the Saxon jars must be set in a CLASSPATH environment variable. They are bundled in lib/saxon.

In a Unix environment, navigate to the root of your Laika project and run:

$ source bin/laika_env.sh

As an alternative, you may create CLASSPATH environment variable as part of the user's profile.

Note that many rake tasks load the environment, and thus will also fail if the CLASSPATH does not include Saxon.

Install JRuby

Ensure that you have JRuby installed locally (available here: dist.codehaus.org/jruby/) and add <jruby-install>/bin to your PATH environment variable.

On a Linux based system, JRuby can be installed painlessly by untarring as root into /opt. On a Debian based distro, /etc/environment has the global PATH environment variable. You will need to restart X to get this into your root terminal sessions.

Setup Gem and Install Rails

NOTE: For installing gems, you need to decide whether you are installing them locally as a non-root user, or globally as root. The examples below assume root access through sudo, to install the gems globally.

You will need to install Rails for JRuby:

$ sudo jruby -S gem sources -a http://gems.github.com
$ sudo jruby -S gem install rails -v=2.3.5 --no-rdoc --no-ri

Database Adapters

Several commands require the use of rake, which in turn loads the local rails environment and will complain if the configuration files are not set up. So make a local copy of config/database.yml.template as config/database.yml.

Currently the initalization environment depends on the activerecord-jdbc-adapter gem as well, so you will need to install this first.

$ sudo jruby -S gem install activerecord-jdbc-adapter

Next you need to install the database adapter you intend to use for local databases. JDBC adapters for both MySQL and PostgreSQL are referenced in the database.yml.template. Laika's rails database can be either mysql or postgresql. However, the UMLS, ATNA and XDS databases have their own requirements (see below).

$ sudo jruby -S gem install activerecord-jdbcmysql-adapter
$ sudo jruby -S gem install activerecord-jdbcpostgresql-adapter

(if you want to use sqlite3 for development or testing - install:

$ sudo jruby -S gem install activerecord-jdbcsqlite3-adapter

NOTE: this is experimental :) )

Then modify your config/database.yml as needed. Typically this will be the core development, production and test databases used by the Laika Rails application. However, see the following sections if you are setting up ATNA, UMLS or XDS.

ATNA Syslog

If you wish to set up an ATNA syslog database, please see:

wiki.github.com/CCHIT/laika/atna-syslog-server

And follow the instructions contained in github.com/downloads/CCHIT/laika/syslog_server.zip

Regardless of whether you are going to use the ATNA syslog, you will at least need an empty syslog database to prevent errors being thrown when the AtnaAudit model is loaded.

You will also need to set 'use_atna' to true in your config/laika.yml file.

UMLS HOST

Detailed information about UMLS may be found here at NIH:

www.nlm.nih.gov/research/umls/

UMLS is required for Laika's Generate and Format tests. If you have access to an existing UMLS database, specify that in your config/database.yml and make sure that you have the correct database adapter installed (most likely jdbcmysql).

Setting up a local UMLS database requires a lot of space. See the NIH site and search the laika-talk mailing list for more details: sourceforge.net/mailarchive/forum.php?forum_name=laika-talk

XDS HOST

To use XDS you will need to set 'use_xds' to true in your config/laika.yml file and then configure the XDS utility.

The default XDS setup on Laika points to localhost. You can change the initial XDS endpoints by editing the settings.yml in spec/fixtures. If you do not have your own XDS set up, you can use the public registry provided by NIST (more information at 129.6.24.109:9080/index.html); simply change localhost to the following IP address: 129.6.24.109:9080.

If you are not conducting XDS tests, you should leave the XDS database commented out in your config/database.yml

Installing Required Gems

With a functional config/database.yml, you can now use rake to install the rest of Laika's gem dependencies. From the root of your Laika project:

$ sudo jruby -S rake gems:install

If you will be running the test suite, also perform

$ sudo jruby -S rake gems:install RAILS_ENV=test

Database initialization

Make sure your local database server is running and create a new user laika with password laika. You will need to ensure that this user will have access to the laika database. MySQL and PostgreSQL have different authentication and authorization methods; check their manuals. Make sure that your database.yml settings reflect your choice of user/password/database, for example:

# default settings
login: &login
  adapter: jdbcpostgresql
  host: localhost
  port: 5432
  encoding: UTF8
  username: laika
  password: laika

# laika development settings
development:
  database: laika
  <<: *login

To the extent that you have different settings per database environment, move them out of the login: macro and into the specific environment's database settings (development:, production:, etc.)

Save the file as database.yml (i.e., without .template extension). Initialize the databases and load the seed data:

$ jruby -S rake db:create
$ jruby -S rake db:schema:load
$ jruby -S rake db:seed

You will be prompted for information about the administrator account.

NOTE: this only prepares the Laika Rail's databases. Prepation of UMLS, XDS or ATNA databases is a separate installation process not covered in this document. See the above notes for pointers.

NOTE: You must have your classpath set so that Laika can find the Saxon libraries in order to run rake. See 'Environment' above.

CCR Validation

The CCR XSD is proprietary and can be obtained through ASTM for a fee:

www.astm.org/BOOKSTORE/ADJUNCT/734.htm

If you wish to test CCR documents, you will need to obtain the XSD and place it in resources/schemas/infrastructure/ccr as CCR.xsd. The relative path to the XSD resource should be:

resources/schemas/infrastructure/ccr/CCR.xsd

Waldren CCR Validator

To use Steven Waldren's CCR ValidationService, you will need to obtain a copy and place it in vendor/ccr-validation-service (see vendor/ccr-validation-service/README.txt).

You can unpack the ValidationService.war using the 'jar' utility.

$ cd vendor/ccr-validation-service
$ jar -xf ValidationService.war # assuming you have copied ValidationService.war into this directory from SourceForge

You will also need to place a copy of the CCR xsd in vendor/ccr-validation-service/WEB-INF/classes/org/openhealthdata/validation/

This validation service is beta functionality and is likely to change in the future.

Additional Laika Configuration

May be set by copying config/laika.yml.template to config/laika.yml and editing as necessary.

Mail Settings

Laika sends mail for forgotten passwords, and potentially for error notifications (see below).

By default, Laika assumes that it can send mail through a mail server configured at localhost on port 25. To change this, create a copy of config/laika.yml from the config/laika.yml.template and set your mail settings as needed under 'action_mailer:'. See the ActionMailer::Base configuration options for further details (api.rubyonrails.org/classes/ActionMailer/Base.html).

Error Notifications

Laika uses the exception_notification plugin to email application errors encountered on a production server. If you wish to receive email notifications, make sure that you have a config/laika.yml YAML file in place and that the exception_recipients parameter has been set to a list of one or more email addresses who should be receiving error notifications:

exception_notifier:

exception_recipients: [ 'foo@bar.com' ]

Laika Advanced UI Functions

laika.yml also has four switches for activating the UI for ATNA logs, C62, XDS, and PIX/PDQ tests. In addition to setting these switches to true to activate the UI for these functions, you will need to set them ap locally (See XDS and ATNA above; See the github.com/citiustech/laika-pixpdq-adapter for information on setting up a PIX/PDQ server. C62 testing is enabled simply by updating the laika.yml setting, but the test is incomplete.)

GlassFish

NOTE: currently there is a problem with the latest glassfish release (v 1.0+) and the ccr validation service. If you are installing the ccr validator, make sure and restrict yourself to using glassfish v0.9.5, or you will get Java io errors for too many open files if you try and validate a CCR in a generate and format test.

Install the Glassfish server using the Glassfish gem:

$ sudo jruby -S gem install glassfish

GlassFish will use default options for the server if you do not have a glassfish.yml file in your config directory. Laika provides a glassfish.yml.template file that you may edit. Note that GlassFish cannot run as a daemon process on Windows.

Deploying Laika on the GlassFish server is very simple. Make sure your CLASSPATH variable is set:

$ source bin/laika_env.sh

Then run the following command from the root of your Laika project:

$ jruby -S glassfish

Point your browser to localhost:3000/.

Installing/using multiple version of Java in Ubuntu

$ # install both Java 1.5 and Java 1.6
$ sudo aptitude install sun-java5-jdk openjdk-6-jdk

$ # use Java 1.5
$ sudo update-java-alternatives -s java-1.5.0-sun
$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b02)
Java HotSpot(TM) Server VM (build 1.5.0_16-b02, mixed mode)

$ # use Java 1.6
$ sudo update-java-alternatives -s java-6-openjdk
$ java -version
java version "1.6.0_0"
IcedTea6 1.3.1 (6b12-0ubuntu6) Runtime Environment (build 1.6.0_0-b12)
OpenJDK Server VM (build 1.6.0_0-b12, mixed mode)

Deploying to Amazon EC2

NOTE this is currently not supported. Instead load an AMI provided by CCHIT.

Here is a quick run-through of how deployment works so far. The first step is to get a recent AMI of a base system. These instructions assume you're deploying to an instance of Amazon EC2 public AMI 95fc1afc

The deployment scripts install laika into /var/www/laika/DATESTAMP and maintain a link to the latest deployed version as /var/www/laika/current.

From a checked-out copy of the latest CCHIT/master on your local machine:

$ # add your Amazon-supplied SSH key to the ssh-agent
$ ssh-add ~/ec2-keys/mykey.pem

$ # customize your deployment config:
$ cp config/deploy_local.rb.example config/deploy_local.rb
$ vi config/deploy_local.rb

$ # customize your app config:
$ cp config/database.yml.template config/database.yml
$ vi config/database.yml

$ bootstrap the deployment setup server
$ cap deploy:setup
$ cap deploy:update       # bootstrap the code so we can ...
$ cap laika:install_gems  # ... automatically install gem dependencies

$ # once the setup is done, this should be the only command needed to deploy
$ cap deploy:migrations