Setting Up Your Environment

Overview

To set up your environment so you are ready to prepare a customized version of Onyx, you must do the following:

Obtaining the Required Software
Configuring Tomcat
Configuring MySQL
Trying the onyx-demo application

Troubleshooting
Onyx User Guide

Obtaining the Required Software

Software	Suggested Version	Download Link	Use
Java Development Kit	JDK 1.6.x	http://java.sun.com/javase/downloads/index.jsp	You need it to generate a war file and if you're going to build custom questionnaires
Tomcat	6.0.x	http://tomcat.apache.org/download-60.cgi	Servlet container - needed to run Onyx
MySQL	5.0.x	http://www.mysql.com/downloads/mysql/	Database management system
Maven	2.2.x	http://maven.apache.org/download.html	You will use Maven to build custom questionnaires and to generate the war file that will be used to deploy your version of Onyx.
Acrobat Pro	8.x or 9.x	http://www.adobe.com/products/acrobatpro/tryout.html	You need Acrobat if you are going to create electronic consent forms
onyx-demo project (source files and more)	latest	http://svn.obiba.org/sandbox/plaflamm/onyx-demo/	We recommend that you use an SVN client to check out (copy) these files, - src (source files including examples of how to write questionnaire classes) - pom.xml (Maven project file which includes all the dependencies you need to build questionnaires and war file) - exampleKeystore.jks (needed to encrypt data upon export) - settings (project settings if you're working in eclipse)

Configuring Tomcat

After installing Tomcat, you must increase the memory allocated to Tomcat's VM as explained in Tips and Tricks for a Successful Installation.

Configuring MySQL

Before starting Onyx for the first time:

Create a MySQL database instance using the settings in the table below (execute the command "create database onyx" in a MySQL client).
Grant all privileges (CREATE TABLE, ALTER, etc.) to the MySQL user (also "onyx") for that database instance.

Setting	Value
hostname:port	localhost:3306
database name	onyx
username	onyx
password	onyx-demo

Trying the onyx-demo application

We recommend that you familiarize yourself with Onyx by deploying and accessing the onyx-demo application as follows:

Get the war for the onyx-demo application. You can either download the onyx-demo.war file from here or generate it from the source files (by running mvn package command from wherever you installed the source files for onyx-demo (where the pom.xml file is located).
Put the war file in Tomcat's installation directory ($TOMCAT_HOME/webapps). If Tomcat was already running, it should deploy Onyx automatically. If not, start Tomcat and Onyx will be deployed.
Access the Onyx demo application by pointing your browser to http://localhost:8080/onyx-demo.
When you access the Onyx demo for the first time, you will be prompted to create the administrator user and also to provide some details about the Onyx instance (study name, site name and site ID). See the screen below.

Take note of the user name and password you entered. You will need them to access onyx-demo.
To ensure that the demo appointment list loads properly, you must set Collection Site ID to onyx001.

Troubleshooting

If Onyx does not start, the first thing to look at is Tomcat's console output which is written in the logs directory. On Windows, the file is called stdout_XXX.log. On Debian/Ubuntu, the file is called catalina.out.

Onyx User Guide

FYI, the latest version of the Onyx User Guide can be downloaded here.