0. Recommendations

Before proceeding with the installation of OpenNCP please refer to OpenNCP Installation Overview page for the basic information about OpenNCP installation and architecture.

This installation manual was based on an installation with the following software:

• Java 1.7.0_80

• GNU/Linux x86_64

• MySQL 5.6.25

• Apache Tomcat 7.0.70

• Liferay  6.2.5 CE GA6

1. Setup application server

We strongly recommend using the version 1.7_80 (known issues with earlier versions) which is the latest public update of the JDK 1.7 as some of OpenNCP component are not fully compatible with the JDK 1.8.

The software components are able to run on all Java application servers, but we recommend you to install them at an Apache Tomcat instance.

You can download it at http://tomcat.apache.org/ and you should use Tomcat version 7 (version 8 is still not supported).

To perform the installation of the server you may also follow this instructions: http://tomcat.apache.org/tomcat-7.0-doc/setup.html (for Apache Tomcat 7.0)

Don't forget to give execution permission to the files in the bin folder. Also, add the JDBC connector (JAR file) of your database to your Tomcat's lib folder.

You must check if you have some other service running in Tomcat's default ports (defined in its conf/server.xml file) and change them if you do.

You need to define JNDI DataSources to the Apache Tomcat configuration. This is done in the conf/context.xml file. Here is an example file for Tomcat 6.0: context.xml. Just add the definition of the JNDI data sources and change the connection string depending on the DBMS you're using (for MySQL there's no need to change). We'll configure each one of them as we progress through the installation (keep them commented and uncomment when you configure).

For more background information and configuration tips on the JNDI please refer to this JIRA:

2. Adjust configuration parameters

First, you'll need to have a folder named "epsos-configuration" that will hold your configuration files (you can take a quick look at the last step of the guide to see a recommended folder structure for the NCP). The folder is provided hereafter as a zipped file:

Folder content:

OIDs were defined within epSOS-I. It seems that the root used (2.16.17) is not officially assigned. Was it defined by IHE Services? Then we simply incremented the 8xx  number for each country (2.16.17.710.8xx.1000.990.1). At the end, at least for PRODUCTION, each country should get (buy) its own OID from HL7.

The sharing of International Search Masks (forms folder) is a manual process. Currently they're being shared by email between OpenNCP adopters. The central services could be used for that, using their public folder at:  https://webgate.ec.europa.eu/ehealth/tsl/common_files/

Then set the EPSOS_PROPS_PATH environment variable to the path of configuration files folder. You can do this by executing the following command in the terminal window:

For more information about environment variables, you can check: https://help.ubuntu.com/community/EnvironmentVariables for Ubuntu, but that can be applicable to other distros.

2.1 Configuration Manager Database

The bulk of NCP configuration properties (i.e. countries endpoints, truststore locations, and others) is stored in the Configuration Manager database.

The "Setup" section of Configuration Manager explains how to create a database and a hibernate configuration file.

(If you already have an existent setup with the old configuration files - epsos.properties and others - you can also follow the "How To Migrate" section. If you are doing a fresh install please ignore this line.)

2.2 Creation of certificates

You can find more details on how to create epSOS certificates here.

After that, you need to add a new Connector to your Tomcat's conf/server.xml file, in order to configure SSL connections to use the generated keystores and certificates:

• port: should be the port that you want to use for SSL connections. It'll be the port where your web services (PatientIdentification, Consent, etc.) will be exposed;

• keyAlias: your service provider certificate alias;

• keystoreFile: the path to your service provider keystore. This means that your Tomcat will act as a service provider;

• keystorePass: your service provider keystore password;

• truststoreFile: the path to your truststore. This means that your Tomcat will only accept connections from your trusted third-parties;

• truststorePass: your truststore password.
  
  

2.3 NCP First-Time Configuration Utility

To facilitate the process of setting up your NCP instance, you can use a special utility to populate your database with the basic required parameters, related to your scenario.

To do that you just need to fill a provided unfilled properties file according to your scenario, configure the database connection file and execute the utility JAR. 

Find the JAR file in section 3.1 of this manual. You can download the properties and database files here:

Once you have run the utility with success, you may delete both files and the JAR and check if the database was correctly filled, using the appropriate database administration tool.

Be aware that this configuration utility will ignore properties with no value set, so these ones should be added manually to your database.

Note: properties should not use environment variables like '$EPSOS_PROPS_PATH/...'. Instead, the full path should be used.

A full list of the OpenNCP properties can be found here: OpenNCP properties

The following table also provides some important information about the central services (for configurations and terminologies):