/
OpenNCP Installation Manual (deprecated, since 2015-10-29)

OpenNCP Installation Manual (deprecated, since 2015-10-29)

Nov 21, 2015

The main goal of this page is to provide an installation manual for new OpenNCP adopters.

It tries to cover all possible setup and configuration operations and it can be used not only as a step-by-step guide but also as a supporting guide to install a certain component - you can check the table of contents on the right side of the page.

Please feel free to leave suggestions or expose your doubts at the bottom of the page.

Table of contents:

1. Setup application server

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

You can download it at http://tomcat.apache.org/ and you may use the most recent version.

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)

You need to define JNDI DataSources to the Apache Tomcat configuration. This is done to the conf/context.xml file. Here is an example file of Tomcat 6.0 context.xml.

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

Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.
 

2. Obtain artifacts

In order to install OpenNCP, you must obtain the following artifacts (Please use the last versions for each component): 

3. Adjust configuration parameters

First, to hold all your configuration files, you can first start to create a folder and name it "epsos-configuration" for instance. (You can take a quick look at the last step of the guide to see a recommended folder structure for the NCP)

Then you will need to associate the folder location to a environment variable, called EPSOS_PROPS_PATH, you can do it with the following command:

export EPSOS_PROPS_PATH=/opt/epsos-configuration/

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.

Next, you may download and unzip the content from the following file to the newly created folder.

  File Modified

ZIP Archive epsos-configuration.zip

Sept 12, 2013 by Ivo Pinheiro

Folder content:

/epsos-configuration |-- /audit-backup |-- /ATNA_resources |-- /EADC_resources |-- /TM_resources |-- configmanager.hibernate.xml |-- pn-oid.xml |-- ISO_3166-1.xml |-- tm.properties +-- tsam.properties

All the provided files will be used and configured in this manual.

At this step you need to add entries to your country at pn-oid.xml and ISO_3166-1.xml

3.1 Configuration Manager Database

In order to hold the biggest part of your NCP configuration properties (i.e. countries endpoints, truststore locations, and others) you will need to create a database and an hibernate configuration file.

To do that, you may follow the "Setup" section, available at Configuration Manager.

(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.)

3.2 NCP First-Time Configuration Utility

To help you on the process of setting up you NCP, 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 and execute the utility Jar. 

You must have your EPSOS_PROPS_PATH defined and the properties database (with no tables) already created, before using this utility.

You can download the utility, together with the properties file here:

  File Modified

ZIP Archive OpenNCP-configuration-utility.zip OpenNCP first-time configuration utility

Jan 30, 2013 by Marcelo Fonseca

Once you have run the utility with success, you may delete the properties file, the jar and check if the database was correctly filled, using the appropriate database admin tool.

3.3 Create Certificates

You can find more details on how to create and the epsos certificates here 

4. Install and setup components

4.1 TRC-STS

The main purpose of this component it to generate and return security assertions on demand. It is a war application that will run also on your Application Server instance.

In order to install it, you will need to obtain the artifact, named epsos-TRC-STS-X.X.X.war, then it is advised to rename it to just TRC-STS.war.

Next you can just deploy it in your Application Server instance. You can follow this instructions for Tomcat 7: http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html

After that, you can check the property "secman.sts.url" at your ncp properties database to see if it matches the installed application URL.

4.2 TSL-Sync

This component will connect to the central services and fetch all the other countries configuration elements (such as endpoints) to your local properties database, together with all the certificates.

Before running this component, make sure that you already have your trust store and key store already created (under your EPSOS_PROPS_PATH, i.e: $EPSOS_PROPS_PATH/cert), together with their passwords and alias.

In order to install this component, you need to download the war file, following the link in step 2 and deploy it to your server.

Then, according to you configuration. present in the properties database, it will fetch all the central services informations and sync them to your key stores and properties database.

This tool will execute every 5 seconds, you can adjust this time by editing this file, present at the deploy dir:

<application server root>/webapps/epsos-tsl-sync/WEB-INF/classes/quartz_data.xml

From the 2.8.9 version the tsl-sync utility can be run also from the command line. You can see more here TSLSync Home

4.3 TSAM-Sync

The TSAM-Sync component will connect to HealthTerm repository to fetch your country terminologies and load them in your LTR database.

This application is a standalone jar that can be placed in custom location, together with a required group of folders.

For instance:

tam-sync-custom-location |-- conf | |-- epsos.properties | |-- hibernate.cfg.xml | |-- log4j.xml | |-- logging.properties | +-- settings.properties |-- lib | +-- jdbc-connector.jar |-- tsam-sync.jar +-- sync.sh

The conf folder will contain several configuration files that you need to adjust to your scenario. Please pay special attention to:

  • hibernate.cfg.xml: where you will place your database configuration

  • settings.properties: where you will define your credentials to access HealthTerm servers

The lib folder will contain your JDBC drivers.

In the root folder you will find sync.sh, which is a script to help you pass the required parameters to the jar execution.