Setting Up the Server

Overview

Setting up the Onyx server involves some or all of the following tasks:

Fine-tuning Tomcat

For general tips related to Tomcat, see http://tomcat.apache.org/.

The following tips assume that you are using Sun's Java Virtual Machine

General Comments about Tomcat Memory Settings

On most default Tomcat installations, the memory allocated to the service is insufficient. You must increase the memory allocated to Tomcat by tweaking two memory settings. 

• -Xmx
• -XX:MaxPermSize

In the OS-specific procedures below (see [Allocating Memory on Ubuntu] and [Allocating Memory on Windows]), we assume that your server has 2GB of RAM.  We set -Xmx  to 1024 and -XX:MaxPermSize to 256m.

• If your server has more than 2GB of RAM, you can increase the -Xmx setting.  It is not necessary to increase the -XX:MaxPermSize setting.
• If your server has less than 2GB of RAM, you can decrease the -Xmx and the -XX:MaxPermSize settings.  Try to keep the same ratio (4:1).  Do not allocate less than 128m to -XX:MaxPermSize.

Using Tomcat on Ubuntu

Two issues need to be addressed when running Tomcat on Ubuntu: insufficient memory and the security manager.

To allocate memory on Ubuntu

To allocate memory to Tomcat, you need to create an environment variable. If Tomcat was installed using apt, you must edit the /etc/default/tomcat6 file as shown below.

To disable the security manager on Ubuntu

Comment out the #TOMCAT6_SECURITY=yes and add the TOMCAT6_SECURITY=no line as shown below.

Using Tomcat as a Windows Service

Two issues need to be addressed when running Tomcat as a service on Windows: insufficient memory and making the printer available to Tomcat.

To allocate memory on Windows

1. Open the Apache Tomcat Properties dialog in either of these ways:
   • If you have a Tomcat icon on your taskbar, right-click it and select Configure.
   • From the Start menu, select All Programs > Apache Tomcat 6.0 > Configure Tomcat.
2. Select the Java tab.  See screenshot below.
3. Add this line in the Java Options field:  -XX:MaxPermSize=256M.
4. In the Maximum memory pool field, enter the value  1024.

   The Maximum memory pool setting is equivalent to passing the -Xmx argument to Java.

    

To enable printing from Tomcat

When running Tomcat as a Windows Service, make sure that the user running the Tomcat service can use the printer. This is not the case by default. Permissions must be given to the tomcat user in order for Onyx to see the printer you wish to use.

Can someone provide the way to properly do this? CaG fixed the issue by making Tomcat run as a domain user, then login to the server as that user and install the printer. There's probably a better way of doing this e.g.: install the printer as a "system" printer instead of installing it per-user

Configuring MySQL

To check the database connection settings

The default Onyx connection to the MySQL server uses the settings shown in the table below.  They are defined in the onyx-config.properties file, which is Onyx's main configuration file.  

Your organization may have already changed the defaults. You can check the values in the onyx-config.properties file (see What You Need from Your Organization). If the settings are different from the defaults shown in the table, note them so you can use them when Creating a Database for Onyx in MySQL.

To create a database for Onyx in MySQL

You must create a database for Onyx  in MySQL, and you must also set up a user that has all privileges on that database.  When Onyx starts for the first time, it will automatically create its schema in this database.

In a MySQL client:

1. Execute the command: create database onyx  (or whatever name that defined at the end of this line in onyx-config.properties: org.obiba.onyx.datasource.url=jdbc:mysql://localhost:3306/onyx}
2. Ensure that the MySQL user (onyx in this case) is granted all privileges on that database instance (CREATE TABLE, ALTER, and so on).

Alternatively, in the MySQL Administrator application:

1. Select Catalogs.
2. Right-click in the field that lists the existing schemata, and select Create New Schema. 
3. When prompted for a name for the new schema, enter onyx or whatever name was defined at the end of this line in onyx-config.properties: org.obiba.onyx.datasource.url=jdbc:mysql://localhost:3306/onyx).
4. Add a new user (with the name onyx or whatever value is defined in this line of onyx-config.properties: org.obiba.onyx.datasource.username=onyx).
5. Assign all priveleges on the new database to the new user.

Setting Up an SSL Connection

To set up Onyx to run over a secured connection on the local network, you must do two tasks on the Onyx server: create a keystore and configure Tomcat to use an SSL connection.

The procedures in this section use the following shortcuts to refer to certain directories: JAVA_HOME = the directory where java is installed CATALINA_BASE = the directory where Tomcat is installed

To create a keystore for the SSL connection

1. From the JAVA_HOME directory, execute this command:
2. When prompted, enter the requested information for the certificate and a new password.
3. Export the certificate to a file. You will import this file on each of the client workstations. See Setting Up the SSL Connection to Onyx

To configure Tomcat to use an SSL connection

Edit the file CATALINA_BASE\...\conf\server.xml as follows:

     1. Comment out this section:

      2.  Remove comments from this section:

     3.  In the <Connector> element, add the following attributes:

          where "keystore\onyx.jks" and "password" are the values you entered when Creating a keystore for the SSL connection.

Generating a Key and Certificate for Data Export

Onyx can export data to one or more export destinations (see Configuring Data Export and Purge). If your organization has decided to encrypt participant data upon export to a particular destination, you must generate a key and certificate for that destination.

You can check whether or not data is supposed to be encrypted on export, look in the file export-destinations.xml which is in your custom-onyx.war file (What You Need from Your Organization). If any of the destinations include an <encrypt> element, the data will be encrypted on export.

You will need the key and certificate when you carry out the procedure for Deploying Onyx.  You can use a utility (like openSSL) to generate keys and certificates. For a Windows program that uses openSSL to generate keys and certificates, see Shining Light Productions.

Fine-tuning the Onyx Configuration

The global configuration settings for Onyx are contained in the file onyx-config.properties. See What You Need from Your Organization.

As a minimum, you should check the configuration settings listed in this section. If you think other settings need to be fine-tuned, see Customizing the Global Configuration in the Onyx Customization & Configuration Guide.

To check the application mode

Onyx should be configured to run in deployment mode. This is very important since it improve the overall performance of the application. Check that the following property onyx-config.properties is set to deployment in :

To set the printer

On startup, Onyx decides 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 PostScript printing, then Onyx will fall back to using the system's default printer. If that printer does not support PostScript printing, Onyx will not be able to print reports.

You can change the printer that Onyx should look for at startup by editing this line in onyx-config.properties.

To set up the appointment list

1. Check the input and output directories for the appointment list file. The output directory is optional. The default paths are shown below. They may have been changed in your version of Onyx.
   WEB-INF/config/onyx-config.properties
2. Create the input and output directories on the Onyx server.
3. If your organization gave you an appointment list file, put it in the input directory.

To set up the data export directory

1. Check the export directory setting in onyx-config.properties. The default export directory is target in Onyx's current working directory (usually the Tomcat home directory). It may been changed in your version of Onyx.
   WEB-INF/config/onyx-config.properties
2. Create the export directory on the Onyx server.

To set up the keystore for data export

1. Check where the keystore file should be written to. The default path and filename are shown below. They may have been changed in your version of Onyx.
   WEB-INF/config/onyx-config.properties
2. Change the password for the keystore and save onyx-config.properties.
3. Create the keystore directory on the Onyx server.

Deploying Onyx

To deploy Onyx, you need a war file (custom-onyx.war) containing a customized version of Onyx.  If you do not already have it, see here

You must enter the custom-onyx part of the war filename when you access Onyx in a browser in the procedure below.

# Copy the war file to the webapps directory in the Tomcat installation directory $TOMCAT_HOME/webapps.

1. If Tomcat is already running, it should deploy Onyx automatically. To check if Tomcat is running on Windows: 
   1. Select Control Panel > Administrative Tools > Services > Apache Tomcat).
   2. Click Start if Tomcat is not running. Onyx will be deployed when Tomcat starts.
2. Check that you can access Onyx by opening a browser and pointing it to: http://localhost:8080/custom-onyx.  If you cannot access Onyx, try restarting Tomcat. If you still have trouble, see Troubleshooting.
3. When you access Onyx for the first time, you must complete the Onyx setup page (see the screenshot below) as follows:
   1. Enter details about the Onyx instance (study name, site name and site id).
   2. If you configured Onyx to Generate Participant Identifiers Automatically, you will have to specify the Identifier Prefix and the First Indentifier (starting point for generating the identifiers). See [Configuring Participant ID Generator] for more details about generating identifiers.
   3. Set up an account for the Onyx Administrator.
   4. Set the Session Timeout (minutes) to at least 45 or 60 (which should be enough for any physical measurements that must be performed).
   5. If your organization will encrypt participant data upon export, copy and paste the certificate you generated for this purpose into the field provided. If you did not generate a certificate yet, see Generating a Key and Certificate for Data Export.

Take note of these values for future reference: Administrator's user name and password. You will always need them to log in to Onyx. Collection Site Id. This value will be used in the appointment list file. If your organization has or will have several sites (each with its own Onyx server), each site should have a unique Id. The value can be alphanumeric, but should not contain spaces.

Checking the Deployment

Here are a few items to check after you have deployed Onyx:

• If your data will be encrypted upon export (see Generating a Key and Certificate for Data Export), check that the file onyxKeyStore.jks was created at the location defined by the property org.obiba.onyx.keystore.file in onyx-config.properties.
• If you put an appointment list file in the input directory (see Setting up the appointment list), check that you can update the appointment list from the Participants tab of the Onyx user interface.

Troubleshooting

The first place to look is 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.

Miscellaneous

Consent Form Submission Problems

You may encounter an error when attempting to submit a consent form, especially a large multi-page consent form written in a double-byte character set. This error occurs because the consent form is too large to be stored in the database. To get around this, you must modify the MySql database settings to allow storage of larger amounts of data. The configuration file that you must edit is my.ini on Windows and my.cnf on Linux. This is the line you need to change:

To start, try a value of 3M (for 3 megabytes). If it still doesn't work, increase the value. You will need to restart the MySql database server after making the change.

Search Onyx Documentation