Introduction
This page describes how to locally install a demo configuration of Onyx. Going through this process requires prior knowledge of Java, Tomcat and MySQL.
Requirements
| Software | Suggested Version | Download Link |
|---|---|---|
| Java | JDK 1.6.x | http://java.sun.com/javase/downloads/widget/jdk6.jsp |
| Tomcat | 6.0.x | http://tomcat.apache.org/download-60.cgi |
Install and Configure Tomcat
Follow the instructions for installing a Tomcat Servlet Container. It is imperative that the memory allocated to Tomcat's VM be adjusted. Read this section of our wiki for more details on setting up Tomcat for Onyx.
Database
Onyx will create its own file-based database automatically upon starting for the first time. This file will be created in the target directory in Tomcat's home.
Obtaining the WAR File
The latest Onyx Demo WAR file can be downloaded here.
The Onyx Demo is already configured with reasonable settings. You can optionally modify these settings as described below
Once the WAR file has been downloaded, copy it to the webapps directory under Tomcat's installation directory $TOMCAT_HOME/webapps. If Tomcat was already running, it should deploy Onyx automatically, otherwise, Onyx will be deployed once Tomcat is started.
To access Onyx, point your browser to http://localhost:8080/onyx-demo.
Finalizing your Onyx Installation
When accessing Onyx for the first time, you must create the administrator user and also provide some details about the Onyx instance (Study name, site name and site code).
 | For the purpose of the demo, you must use onyx001 as the value of your Site's code. This will ensure that the demo list of appointments can be loaded properly |
Using Onyx
The latest version of the Onyx User Guide can be downloaded here.
Changing Onyx Configuration (Optional)
The configuration file is located within the demo's WAR file. To modify the configuration file, you must unzip the contents of the WAR file, make modifications, then re-create the WAR file. The configuration file is WEB-INF/config/onyx-configuration.properties.
Modifying the database settings
The database settings are specified at the end of the file.
| Property Key | Description |
|---|---|
| org.obiba.onyx.datasource.driver | the JDBC driver to use (note that its corresponding JAR file must be placed under WEB-INF/lib) |
| org.obiba.onyx.datasource.url | the JDBC url for connecting to the database |
| org.obiba.onyx.datasource.username | the username to use for connecting |
| org.obiba.onyx.datasource.password | the password to use for connecting |
| org.obiba.onyx.datasource.dialect | the Hibernate dialect to use (more info here) |
| org.obiba.onyx.datasource.validationQuery | a valid SQL query to issue for testing JDBC connections |
| org.obiba.onyx.datasource.testOnBorrow | whether to test pooled connections before providing them |
Modifying the Printer
On startup, Onyx will decide which printer to use. Onyx will try to find a printer with a particular name. If that printer does not exist, or does not support PS printing, then it will fallback to using the system's default printer. If that printer does not support PS printing, then printing reports from Onyx will not be possible.
You can change the printer to lookup at startup:
| Property Key | Description |
|---|---|
| org.obiba.onyx.pdfPrinterName | the printer name to try before trying the system default printer |
Modifying the Export Directory
By default, the demo configuration will write export files to directory named target under the "current working directory" (this is usually Tomcat's home directory).
You can change this output directory:
| Property Key | Description |
|---|---|
| org.obiba.onyx.export.path | the path to export data to |
Troubleshooting
First thing to look at is in Tomcat's console output which is written in the log directory. Under windows, the file is called stdout_XXX.log on Debian/Ubuntu, this file is called catalina.out.