Opal Installation Guide

Contents of this Guide

Introduction

Opal is an application that runs on a server. Users access Opal via the web or on client workstations via a secure shell connection over a network.

This guide is for whoever will set up Opal--typically, a system administrator.

Installing Opal

Opal is distributed as a Debian package and as a zip file. Installing Debian package is recommended on Debian-like Linux systems.

The resulting installation has default configuration that makes Opal ready to be used. Once installation is done, see how Configuring Opal.

Installation of Opal Debian package (recommended)

OBiBa Debian repository is available at http://pkg.obiba.org. To proceed installation, do as follows:

1. Install Debian package. Follow the instructions in the repository main page for installing Opal. The resulting default setup is:

   Directory	Description
   /usr/share/opal	Opal binaries, BIRT report engine, web application etc.
   /etc/opal	Opal configuration directory (symbolic link /var/lib/opal/conf).
   /var/lib/opal	OPAL_HOME environment variable.
   /var/lib/opal/fs	Default location of Opal file system.
   /var/log/opal	Opal log messages.
   /etc/init.d/opal	Opal Service script.
   /etc/default/opal	Options of Opal Service script.

2. Manage Opal Service: after package installation, Opal is running: see how to manage the Service.

Installation of Opal Zip distribution

To install Opal zip distribution, proceed as follows:

1. Download Opal distribution from here.
2. Unzip the Opal distribution. Note that the zip file contains a root directory named opal-server-x.y.z (where x, y and z are the major, minor and micro releases, respectively). You can copy it wherever you want. You can also rename it. The content of this zip file is:

   Directory	Description
   bin	Server startup scripts.
   birt-runtime-xxx	BIRT report engine.
   conf	Configuration directory; the Opal "home" will refer to the parent directory.
   lib	Various libraries required by Opal.
   update-site	Opal Eclipse plugin update site.
   webapp	Web front end for Opal.

3. Separate configuration and binaries directories (optional): it is possible to install at different places:
   • the configuration directory (conf),
   • the binaries directories (bin, lib, webapp etc.).
4. Run Opal Upgrade Command. This step will create/update the database schema for Opal and will start Opal: see Upgrade Command.

Configuring Opal

Default configuration makes Opal ready to be used but you should configure Opal to match your needs:

1. Configure the Users Authentication Directories. See Users Authentication Directories Configuration.
2. Configure databases, servers and other properties: see Opal Base Configuration File.
3. Configure the File System Root: see File System Root.
4. Restart Opal: see how Launching Opal Server.
5. Use Opal to check every thing is up and running: see Using Opal.

The following configuration files are available in the OPAL_HOME/conf directory.

Users Authentication Directories Configuration

The security framework that is used by Opal for authentication, authorization etc. is Shiro. Configuring Shiro for Opal is done via the file OPAL_HOME/conf/shiro.ini.

More information about how to configure Shiro using the INI file can be found here.

Default configuration is a static user 'administrator' with password 'password' (or the one provided while installing Opal Debian package).

LDAP and Active Directory Authentication

Opal can authenticate users by using an existing LDAP or Active Directory server. This is done by adding the proper configuration section in the shiro.ini file:

The userDnTemplate should be modified to match your LDAP schema. The {0} will be replaced by the username provided at login. Authentication will use the user's credentials to try to bind to LDAP; if binding succeeds, the credentials are considered valid and authentication will succeed.

There is currently no support to extract a user's groups from LDAP. This will be added in a future release.

Opal Base Configuration File

The file OPAL_HOME/conf/opal-config.properties is to be edited to match your server needs.

Database Configuration

Opal is made of two distinct databases: one for the holding the participants identification keys and another one for holding the variable catalogue and participant data. Opal must have access to both databases. Defining a different database user for each of these databases ensures the participant data privacy. See Participant Identifier Separation section for more details.

Configuration file edition

The database configuration properties in conf/opal-config.properties must be edited to fit your environment. Currently the default database is HSQL and there are examples for MySQL.

Comment out the appropriate lines for your configuration. Edit the properties to what is configured for your system. For example the username and password properties have to be changed for your environment.

For more information on how to configure the datasource, follow this link about Hibernate JDBC.

Database for data:

Database for identifiers:

Validation Query

Opal needs to test each connection before using it. This requires executing a statement on each connection. Since this statement cannot be written in a database-agnostic way, it needs to be configured for you database type.

Database creation

Create the above configured Opal schemas (for the 'opal' and 'key' databases) on your database system(s) (does not apply to in-memory HSQL database).

Make sure the corresponding database users are granted all privileges on their respective database instances (CREATE TABLE, ALTER, and so on).

MySQL

The required MySQL JAR files are already deployed within the .zip file. All you need to do to use MySQL is to make the configuration changes as described above.

At the time of writing this document, MySQL 5.1.x is recommended.

Important Note When Creating the Databases When creating the MySQL database that Opal should connect to, make sure the character set is specified as UTF-8: CREATE DATABASE opal CHARACTER SET utf8 Also, make sure your JDBC URL specifies the encoding to use by using a URL parameter: "characterEncoding=UTF-8". Example: "jdbc:mysql://localhost:3306/opal?characterEncoding=UTF-8"

HSQL

HSQL is a Java implementation of an RDBMS. It has the ability to be embedded inside another application: it does not require a server running an previously installed instance. As such, it is a great candidate for testing a deployment. It is not recommended for production environments.

The required HSQL JAR files are already deployed within the downloaded package. All you need to do to use HSQL is to configure the settings as described above.
For information on hibernate.dialect: follow this link for a list of available Hibernate dialects.
HSQL jdbc url's are described here.

Other Databases

It is possible to configure other databases such as Oracle but because they have not been tested they will not be discussed here until the need arises.

Identifiers Table Configuration

The identifiers are stored in a Datasource Table which names can be specified.

SSH Server Configuration

Opal is accessible using SSH clients: command line user interface and SFTP are available through SSH connections. The SSH connection port can be configured.

HTTP Server Configuration

Opal web services and web application user interface can be accessed through HTTP or secured HTTP requests. The HTTP(S) connection ports can be configured.

The HTTPS server requires a certificate. If none can be found Opal creates a default one to ensure that HTTPS is always available. It should be configured afterward, following the procedure described in HTTPS Configuration.

SMTP Server Configuration

Opal is able to send emails to notify that a rapport has been produced. To allow this, it is required to configuration to a SMTP server.

Character Set Configuration

When reading/writing files, if a character set is not specified, Opal defaults to ISO-8859-1. This is used for example when reading/writing CSV files.

The default character set is configurable. To configure it, edit the file conf/opal-config.properties and modify the following configuration property:

Rserve Configuration

Opal is able to perform R queries by talking with a running Rserve. Opal does not provide R and Rserve. Rserve version must be 0.6+. The properties for connecting to Rserve are the following:

Opal Main Configuration File

The file OPAL_HOME/conf/opal-config.xml is to be edited to match some of your server needs.

File System Root

Opal offers a "file system" in which users may manipulate files without having a user defined in the OS running Opal. That is, all interactions with the underlying file-system go through a unique system-user: the one that runs the Opal server.

The Opal file system root is set by default to be OPAL_HOME/fs. To change it, modify the following statement:

Several types of file root names are recognized:

• Absolute URI. These must start with a scheme, such as 'file:', followed by a scheme dependent file name. For example:

  • file:/c:/dir/somedir

• Absolute local file name. For example, /home/someuser/somedir or c:\dir\somedir. Elements in the name can be separated using any of the following characters: /, \, or the native file separator character. For example, the following file names are the same:

  • c:\dir\somedir

  • c:/dir/somedir

Executing Opal

Launching Opal Server

Service

When Opal is installed through the Debian package, Opal server can be managed as a service. Opal service always runs with upgrade argument which makes Opal first run and upgrades transparent.

Service Environment

Options for the Java Virtual Machine can be modified if Opal service needs more memory. To do this, modify the value of the environment variable JAVA_ARGS in the file /etc/default/opal.

Service Script

Main actions on Opal service are: start, stop, status, restart. For more information about available actions on Opal service, type:

service opal help

Service Logs

The Opal service log files are located in /var/log/opal directory.

Manually

The Opal server can be launched from the command line. The environment variable OPAL_HOME needs to be setup before launching Opal manually.

Command Environment

Configure the following environment variables:

Regular Command

Make sure Command Environment is setup and execute the command line (bin directory is in your execution PATH)):

• Windows console:

  opal.bat

• Unix shell:

  opal

Upgrade Command

Running this command is required to create/upgrade the database schema, either when installing Opal for the first time or upgrading Opal from a previous version.

Make sure Command Environment is setup and run the following command:

• Windows console:

  opal.bat --upgrade

• Unix shell:

  opal --upgrade

The upgrade command can be executed safely several times.

Executing this command upgrades the Opal server and then launches it.

Command Logs

The Opal server log files are located in OPAL_HOME/logs directory. If the logs directory does not exist, it will be created by Opal.

Using Opal

Accessing Opal from the Web

To access Opal with a web browser the following urls may be used (port numbers may be different depending on HTTP Server Configuration):

• http://<servername>:8080 will provide a connection without encryption,
• https://<servername>:8443 will provide a connection secured with ssl.

See Opal Web Application User Guide for more details.

Starting Opal Console

Once the server is started, try to access it using a SSH client. See Starting Opal Console in the User Guide for more details.

Troubleshooting

Always check the logs of Opal to know what went wrong: either Service Logs or Command Logs depending on how Opal was launched.