This section describes how to set up a Linux shell account to build an application using Ruby on Rails and the Bridge Software Development Kit (SDK). It presumes you have a development environment that is connected to an existing, functional installation of the Bridge platform. Development environments are almost always virtual machines provided by Analytical Informatics to customers and partners.

Prerequisites

Development environments run Linux, so you need to be comfortable and familiar with a command-line shell and running POSIX commands such as cd, cp, mv. Most developers will be connecting remotely to the development environment, so experience with SSH is also required.

Getting Started

AI is happy to assist developers in configuring or accessing the best environment possible to build applications: for existing customers and partners, this is typically a development system in your existing environment. For new partners or potential customers, AI can provide access to a cloud-hosted sandbox with artificial data created by a "Virtual Hospital" application that simulates hospital data workflows: developers have access to this tool to create data and walk through various workflow steps to test all parts of an application.

If you would like to get access to a development environment, please email us and we will work with you to grant access to the best environment for your needs. This includes providing access to the SDK binary, credentials for a development server, and a personalized, interactive environment walkthrough to confirm connectivity and validate configuration so you can get started on the right foot.

Environment Overview

Unlike a typical Rails application which has a relatively straight-forward database dependency (usually handled by a gem), a Rails application for the Bridge platform has some additional complexity and requirements:

Additionally, unlike a typical Rails app, an instance of Bridge with clinical data is required to provide data and SSO sources, so the SDK itself is not adequate to start writing an application.

Differences Between Development and Production

Given the above requirements, there are some noteworthy differences between development and production environments:

Component Development Production
Web Server WEBrick Wildfly
SDK binary referenced in config/application.rb shared module in wildfly and required in jboss-deployment-structure.xml
app-specific database config/database.yml + jndi-properties file data-source referenced in config/database.yml
AMQP connection provided by SDK provided by SDK
Assets not pre-compiled pre-compiled
Logs log/development.log threaded in with other applications in wildfly server.log
URL http://server.example.com:3000/controller/action http://server.example.com/appname/controller/action
Packaging source code WAR file

Development workflows

AI provides support and documentation for how to develop Rails applications in Linux. We are working hard to improve support and tooling for our Windows-based developers, but at this time there is still some requirement for Linux command-line interfacing to run servers, etc. We always welcome feedback and suggestions to improve these processes and documentation.

Linux development

This workflow is what AI recommends, has the most experience with, and uses internally to develop all our applications. It is designed around a developer using SSH to remotely connect and develop on a Linux development environment.

Setting up Ruby with rvm

Log into the development environment via SSH, then run the following commands:

gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm
rvm install jruby-1.7.16
rvm use --default jruby-1.7.16
gem install mime-types:2.6.2 rails:4.2.0
# In order to solve a recent conflict in rvm and bundler:
gem uninstall -i ~/.rvm/gems/[email protected] jruby-openssl

Java Classpath

For the development environment to interface with the server, you need to add a jndi properties config (clojure) file to the Java classpath. Here is an example that will need to be edited to provided the correct database and rabbitmq credentials.

{:names {}
 :properties {"harbinger-config"
              {"cometd-amqp.url" "http://localhost/cometd-amqp/cometd"
               "harbinger.amqp.host" "localhost"
               "harbinger.amqp.user" "guest"
               "harbinger.amqp.password" "guest"}
              "harbinger-jpa-config"
              {"hibernate.search.default.indexBase" "/path/to/lucene/indexes"}}

 :data-sources {"jdbc/harbinger"
                {:database "harbinger" :server "localhost" :user "harbinger" :password "harbinger-user-password"}}}

We recommend you add this to your application directory and name it jndi-config.clj. Then you can use the launch scripts provided by the vanilla-rails-app or rails-developer-tutorial projects without altering them or setting your CLASSPATH more permanently.

Windows Development

To connect to the need a third-party application to use SSH on Windows. The most popular package is PuTTY, download the Windows installer package. For easier file transfers, you can also use WinSCP, download the Installation package.

Once you are connected to the Linux environment through SSH, you can follow the above Linux instructions to continue setup.

If you prefer to use a native IDE/editor to write code, you can map your home directory as a drive on Windows using SftpNetDrive, a commercial utility. You will still need to use PuTTY to run commands like starting a server, etc. and complete the initial setup above.

Tutorial Application

Download the tutorial application to follow along with the rest of the tutorial and for use in your development environment.

Vanilla Application

Download the "vanilla" Rails application if you are building a new application. The vanilla application is an up-to-date Rails project that is pre-configured for Bridge application development. It includes the correct gems, database init scripts, etc. and there is a rename.rb script to rename the application that saves you from needing to edit dozens of files manually or fighting version issues.

The Vanilla Rails application contains a small React setup to get you started with React. If you would not like to use React in your application, a remove_react.rb script is available to remove all React files and references.