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

• Java 1.7.0_75
• GNU/Linux x86_64
• MySQL 5.6.25
• Apache Tomcat 7.0.62
• Liferay  6.2.0 CE GA1

1. Setup application server

- You should be using the latest version of Java 1.7 (version 1.8 is still not supported). You should also use Tomcat version 7 (version 8 is still not supported). S Issue with Java 1.7.0-25, we should recommend to use the latest JDK1.7.
- Don't forget to give execution permission to the files in the bin folder.
- Add the JDBC connector (JAR file) of your database to your Tomcat's lib folder.
- 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.

2. OpenNCP artifacts

-  Joao Cunha - Change TSL-Sync bullet to JAR: "TSL-Sync (JAR)"

• TSAM-Exporter (JAR): https://joinup.ec.europa.eu/nexus/content/repositories/snapshots/eu/europa/ec/joinup/ecc/epsos-cdadisplaytool/epsos-tsamexporter/
• TSL-Editor (JAR): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/epsos-tslutils/epsos-tsl-editor/
• RichClient - eID Level 1 (JAR): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/org/openecard/richclient/

S If the NCP uses an infrastructure with proxy, we need to add info related to the new proxy configuration setup included into the epsos-utility Jar.

3. Adjust configuration parameters

- Joao Cunha - epsos-configuration.zip is missing 2 folders and 1 file (see attachments at the end of this page):

• ATNA_resources/
• forms/                    ## Portal S also for epsosWeb and linked to the central services ongoing analysis, how the files are uploaded/downloaded manual or automatic?
• hcer.properties

- Joao Cunha - How do PN's know their OID (used in pn-oid.xml)?

- Stéphane Spahni - 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://ecrtsppt.conet-services.de:8445/common_files/

3.1 Configuration Manager Database

1. Database setup

- In MySQL, the database name does not support dots ('.'), so the database should be named "epsos_properties".

2. Hibernate file setup

- Joao Cunha - The hibernate file already exists in EPSOS_PROPS_PATH and should already have the configuration shown. In case you're using MySQL, to avoid a "portalb is temporarily unavailable" error message in the Portal due to MySQL's wait_timeout being exceeded (that is, no requests made during that time), you should use the following setup:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <session-factory>
        <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property>
        <property name="hibernate.connection.url">jdbc:mysql://databasehost:3306/epsos_properties?useUnicode=true&amp;characterEncoding=UTF-8&amp;useFastDateParsing=false</property>
        <property name="hibernate.connection.username">username</property>
        <property name="hibernate.connection.password">password</property>
        
        <!-- Echo all executed SQL to stdout -->
        <property name="show_sql">yes</property>
        <property name="hibernate.hbm2ddl.auto">update</property>
        
        <property name="hibernate.connection.provider_class">org.hibernate.connection.C3P0ConnectionProvider</property>
            <property name="hibernate.c3p0.min_size">1</property>
            <property name="hibernate.c3p0.max_size">50</property>
            <property name="hibernate.c3p0.timeout">7200</property>
            <property name="hibernate.c3p0.max_statements">50</property>
            <property name="hibernate.c3p0.validate">true</property>
        <property name="hibernate.c3p0.idle_test_period">30</property>
        <property name="hibernate.c3p0.preferredTestQuery">SELECT 1 FROM DUAL</property>
        <mapping class="eu.epsos.configmanager.database.model.Property"/>
    </session-factory>
</hibernate-configuration>

3.2 NCP First-Time Configuration Utility

- Joao Cunha - Add to the properties file the following properties (and fill them):

S Adding info related to proxy configuration if needed. And it could be also relevant to know which properties are required by components and what are their roles.

Stéphane Spahni Added several keys that were in my properties file! The problem is that I am not sure they are used! Should check the source code for determining which ones are really used and which ones are inherited from the Spirit config

This file will be used to initially populate the epsos-properties database.

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.

Joao Cunha - This table should also figure in the manual:

3.3 Create Certificates

- Create the following directory structure:

$EPSOS_PROPS_PATH
	|-- /cert
		|-- /PPT
			|-- /conf
			|-- /pem 
			|-- /private
			|-- /ROOT
			|-- /test_requests

- You should create the CA certificate inside ROOT folder, by running the "ROOT Certificate Creation" script.
- Put the 3 configuration files inside conf folder, like this: Stéphane Spahni: we initially had 5 certs: Service Consumer, Service Provider, VPN client, VPN server, Digital signature. VPN client seems not to be used anymore. What about SP ? 

• Service Consumer => conf/sc.conf
• VPN Configuration File => conf/vpns.conf
• Digital Signature Configuration File => conf/sign.conf

- Joao Cunha - Creation of keystore and truststore in $EPSOS_PROPS_PATH/cert/PPT ## ask Stéphane Spahni: Has to be the in same directory as mentioned in the initial config script above
- The script for creating the self signed certificates should be put in $EPSOS_PROPS_PATH/cert/PPT
- In the script there is only one variable $password but it is used both for the keystore/truststore and CA private key. If they differ, it gives an error.
- Joao Cunha - Please, confirm this issue with the script:

cat $country-ncp-obj-self-sign.pem ROOT/$country-ca.pem > pem/$password-objsign.pem

The output file should be $country-objsign.pem, otherwise you get a "keytool error: java.io.FileNotFoundException: pem/pt-objsign.pem (No such file or directory)" when trying to import the certificate to the keystore.

S Into the old installation manual, the recommandation is to create 1 keystore per service/key, but we provide a script with only one keystore generated, we could modify the keystore creation script in order to follow our recommandation or just add a warning about this topic?

Stéphane Spahni VPNserver used by OpenSwan; Service provider = NCP server certificate ? Signature = NCP's signature? Service consumer = NCP's client signature?

These scripts are only available for Linux env, should we propose one for Windows also?

A summary about the role of the keystore and the trustore could also be added to this chapter, because I remembered that I was wondering for a long time what are the role of each keystore and trustore and also which component required which key etc. and also the link with the properties stored into the EPSOSProperties database (CfgManager).

4.1 TRC-STS

- Before the deploy, configure the jdbc/ConfMgr data source in your Tomcat conf/context.xml to connect to your epsos properties database.

4.2 TSL (Trusted Service List)

OpenNCP instances need to share their configurations (endpoints, certificates, etc) with each other. The current way to do this is by placing those configurations in the central services, providing a specific kind of file: the TSL file. Each country needs to create a TSL file with its configuration and upload it to the central services. This can be done with the help of the TSL-Editor. Each country can download these files from the central services and update their local installation by running the TSL-Sync. 

4.2.1 TSL Files

The complete specification of the TSL files and its usage in the eHealth domain (the specific fields and values to be used) can be found in epSOS Deliverable 3.4.2 - section 4.4 "epSOS Trusted Service List" or in Fraunhofer's Wiki page on epSOS Trust Service List - ETSI TS 102 231 Binding.

4.2.2 TSL-Editor

Stéphane Spahni Put a link to the tutorial videos & manual. I think there were uploaded somewhere in the wiki? Joao Cunha: well remembered, they are attached in the installation manual page, I'm going to add some text about it (Alen Vrecko (Unlicensed) check this).

You can find a video tutorial on how to use the TSL-Editor in the following attachment: Webinar TSL-Editor & SyncApp (name of file: 3_Massi_webminar_TSL-Editor. It has to be run with Netviewer_NetPlayer, also provided in the folder). In this other attachment - TSL-Editor 2.3 -, you can find some old version of TSL-Editor which packages some documentation (namely /Doc/TSL_Creation_SbS.doc) as well as a properties file (/TslEditor2.3/tsleditor.properties) that may be useful.

Regarding the "Distribution point" field, it must point to the current central services provider (CONET):

• PPT: https://ecrtsppt.conet-services.de
• Production: https://ecrts.conet-services.de

In order to be able to upload the file to the central services, a pair of SSH keys must be generated, with the public key being sent to CONET, whom must also create the username and folder for the country. For more information about CONET's contact point on this topic, please leave a request to the OpenNCP Community (for now, use the comments section of this page). The upload path will vary: in PPT environment, it'll be /sftp/<CCC>/PPT ; in Production, it'll be /sftp/<CCC> , with <CCC> being the 3-letter country code, like "GRE" for Greece, "ITA" for Italy, and so on. The uploaded file can be retrieved using the URLs listed above (port: 8445).

The "Server" field  in the upload dialog box of TSL-Editor has to contain "ecrtsppt.conet-services.de" for PPT and "ecrts.conet-services.de" for Production.

It is possible to override TSLEditor properties by having a "tsleditor.properties" file in the same folder as the JAR file (e.g. to extend the list of supported locales / countries for the Scheme Territory field).

4.2.3 TSL-Sync

S Providing info about how to execute the script and how it works (getting the countries codes into the DB).

- After this sentence "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." add:

• "For each country <cc> (2-letter country code) listed in ncp.countries property, it will retrieve the TSL file stored in the country's tsl.location.<cc> property. It reads the TSL file and updates the internal configuration by:
  • Writing the web services endpoints to the database;
  • Extracting the TLS and VPN certificates, writing their information (serial number and alias) in the database, saving them as .der files in the certificates folder (given by certificates.storepath property) and adding them to the truststore (given by TRUSTSTORE_PATH property);
  • Extracting the signature certificate, saving it in the certificates folder and truststore;
  • In the end, an audit log is written."

- Insert this property in the database:

• 'scheduled.time.between.failed.logs.handling.minutes' - '60' Joao Cunha: added this to the initial properties configuration file.

- TSL-Sync is also available as a standalone JAR file that should be placed and run in a custom location:

/tsl-sync-custom-location
	|-- tsl.sync.jar

4.3 TSAM-Sync

- You'll need to add the Conet certificate to your JVM's truststore (cacerts). See this link: http://stackoverflow.com/questions/6908948/java-sun-security-provider-certpath-suncertpathbuilderexception-unable-to-find
- Edit log4j reference in sync.sh to -Dlog4j.configuration=file:///$TSAM_DIR/conf/log4j.xml ($TSAM_DIR should be a script variable that references tsam-sync folder)
- Change the following property in the tsam-sync/conf/settings.properties

• webservice.url=https://ecrtsppt.conet-services.de/webservice/commonTerminologyService2.0

- Before the deploy, configure the jdbc/TSAM data source in your Tomcat conf/context.xml to connect to LTR database (ltrdb).

- This sync.sh script has to be run manually.

4.4 Transformation Syncronization Access Manager (TSAM)

- OK

4.5 Transformation Manager (TM)

- This component is used for data transformation from a national language to the epSOS Reference Terminology or for data transformation from the epSOS Reference Terminology to a national language.

- In your epsos-configuration/tm.properties, add the following properties:

- Joao Cunha - Also, the following files do not exist:

4.6 Automatic Data Collector (eADC)

- Automatic data collection is a feature requested to the NCP to provide information to evaluate the epSOS interoperability system performance and to collect statistics on the population using epSOS services.

4.7 Audit Repository (OpenATNA)

Joao Cunha - I think that this section needs to be better organized

- You'll need to deploy the openatna-web WAR to your Tomcat, but before that you need to do the following configurations:
- TLS configuration: parameters in section arr-tls of file $EPSOS_PROPS_PATH/ATNA_resources/ArrConnections.xml have to reflect the values of epsos properties database:

• HostName -> audit.repository.url
• Port (default: 2862) -> audit.repository.port (default: 6514)

- Certificates:

1. copy your ServiceProvider.jks and ServiceConsumer.jks certificates into $EPSOS_PROPS_PATH/ATNA_resources/certs and refer to them in $EPSOS_PROPS_PATH/ATNA_resources/ArrConnections.xml (KeyStore --> ServiceProvider.jks and TrustStore --> ServiceConsumer.jks) OR:
2. In ArrConnections.xml, point to the keystore and truststore in $EPSOS_PROPS_PATH/cert/PPT instead of copying those to $EPSOS_PROPS_PATH/ATNA_resources/certs folder and change the passwords (don't use environment variables, use full paths instead).
3. Example configuration can be seen in step 4: https://openncp.atlassian.net/wiki/display/OP/OpenATNA+Home

- Follow step 1 to set up the database: https://openncp.atlassian.net/wiki/display/OP/OpenATNA+Home . Joao Cunha - confirm the last command (see comments in wiki)
- In $EPSOS_PROPS_PATH/ATNA_resources/openatna.properties, you will need to change password of the DB and edit ihe.actors.dir to point to the ATNA_resources folder.
- If you want to use the logviewer war, you have to add the openatna.properties files to atna.war/WEB-INF/classes
- If you want to use the logviewer war with MySQL, you have to add the jdbc-connector.jar to atna.war/WEB-INF/lib
- You also may need to extend the MaxPermSize of your Tomcat instance (adding -XX:MaxPermSize=256m to your CATALINA_OPTS)
- You should add this line to the TOMCAT setenv.sh script: JAVA_OPTS="-DopenATNA.properties.path=file:$EPSOS_PROPS_PATH/ATNA_resources/openatna.properties $JAVA_OPTS"
- OpenATNA uses property with name scheduled.time.between.failed.logs.handling.minutes in ConfigurationManager database to define the interval in which OpenATNA checks if some audit log was not persisted. In case these logs are found, they will be attempted to re-persist. The default value is 60 (minutes).
- Configure epsos properties to write test audits (see step 5: https://openncp.atlassian.net/wiki/display/OP/OpenATNA+Home)

4.8 Server Side (NCP-A)

- OK

S Providing info about how to modify the port of the server if the NCP doesn't use the default one for axis2.xml file, the proxy etc. Perhaps adding info related to the national implementation in order to connect natinal healthcare system, a kind of how to add national impl or how to work in a mock mode etc.

4.9 Client Side (NCP-B)

- OK

S Providing info about how to modify the port of the server if the NCP doesn't use the default one for axis2.xml file, the proxy etc.

4.10 OpenNCP Portal or epSOS-Web

4.10.1 OpenNCP Portal

Installing OpenNCP Portal

- Be aware that you cannot use the same database for different versions of Liferay (you'll get a corrupted database if you try and there's no way to restore it unless you have a backup).
- Note that the database name in the scripts ('lportal') differs from the one shown in the properties file ('lp62'), but they refer to the same database. Choose the one you like the most.
- Change Liferay's Tomcat ports to others different than the ones you're using in your OpenNCP Tomcat (the chosen ports should be available too): 

- Create portal-ext.properties under Liferay folder
- Add the following properties to your $EPSOS_PROPS_PATH/tsam.properties (connection to your TSAM/LTR database):

- In your Liferay's Tomcat, add to /conf/context.xml the same JNDI resources that you defined in your OpenNCP's Tomcat
- (Trillium): Create "hcer" database (with the script below) and set the connection properties in your $EPSOS_PROPS_PATH/hcer.properties

CREATE TABLE IF NOT EXISTS `hcerdocs` (
  `documentbody` text NOT NULL,
  `creationDate` datetime DEFAULT NULL,
  `creator` varchar(255) DEFAULT NULL,
  `patient` varchar(255) DEFAULT NULL,
  `fromcountry` varchar(20) DEFAULT NULL,
  `docid` bigint(20) NOT NULL AUTO_INCREMENT,
  PRIMARY KEY (`docid`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;

- In order to provide eID functionality in the Point-of-Care, add the jnlp folder to your Liferay's tomcat-X.Y.ZZ/webapps folder. This folder should have the following content:

/jnlp
	|-- /css
	|-- /img
	|-- /js
	|-- README.md
	|-- index.html
	|-- richclient-X.Y.Z.jar
	+-- openecard.jnlp	

In each new version of the eID artifacts, the JAR file and the JNLP file must be updated. The JAR file can be found in Joinup (section 2). The JNLP can only be found in OpenNCP Bitbucket. You can download the folder contents here:

Countries providing eID capabilities for their patients at the country of treatment must update their InternationalSearchMask file to add the storkAttrib attribute to the search fields (you can check the example file from Portugal, InternationalSearch_PT.xml, in epsos-configuration/forms folder). The complete list of values for this attribute is as follows (source code here):

• cardIssuerCountry

• cardType

• healthInsuranceId

• surname

• givenName

• dateOfBirth

• gender

• fiscalNumber

• socialSecurityNumber

• civilianIdNumber

• issueDate

• terminationDate

• photo

- Start Liferay's Tomcat in order to create the deploy folder (zip file doesn't have it due to being an empty folder) and follow the setup wizard to create the default users and other data in the database
- Add some content to epsosportal/WEB-INF/classes/portlet.properties: http://liferay-hacks.blogspot.pt/2014/02/the-curse-of-empty-portletproperties.html

Configuring portal

- Joao Cunha - Add this to the script: INSERT INTO PROPERTY VALUES ('PORTAL_CONSENT_ENABLED','true');

4.10.3 CDA Display Tool (TSAM-Exporter)

In order to correctly translate the CDA, you must run the TSAM-Exporter (make sure you have fetched your country terminologies into your LTR database): TSAM Exporter

• Joao Cunha - Settings.properties file should be updated to have the new properties.

• This application is a standalone JAR file that can be placed in a custom location:

  /tsam-exporter
  	|-- epsos-tsamexporter.jar
  	|-- logging.properties
  	|-- run.sh
  	+-- settings.properties

5. Database Logging

- OK

6. Final Considerations

/opt
|-- /apache-tomcat-7.X.XX
|   |-- /bin
|   +-- /conf
|       |-- context.xml
|   |-- /logs
|   |-- /temp
|   |-- /work
|   +-- /webapps
|       |-- /epsos-client-connector
|       |-- /epsos-ws-server
|       |-- /TRC-STS
|       +-- /atna
|-- /tsam-sync
|   |-- /conf
|   |   |-- epsos.properties
|   |   |-- hibernate.cfg.xml
|   |   |-- log4j.xml
|   |   |-- logging.properties
|   |   +-- settings.properties
|   |-- /lib
|   |   +-- jdbc-connector.jar
|   |-- tsam-sync.jar
|   +-- sync.sh
|-- /tsl-sync
|   |-- epsos-tsl-sync.jar
|-- /tsam-exporter
|	|-- epsos-tsamexporter.jar
|	|-- logging.properties
|	|-- run.sh
|	+-- settings.properties
+-- /epsos-configuration
    |-- /ATNA_resources
    |-- /cert
    |-- /EADC_resources
    |-- /EpsosRepository
    |-- /forms
    |-- /TM_resources
    |-- configmanager.hibernate.xml
    |-- hcer.properties
    |-- pn-oid.xml
    |-- ISO_3166-1.xml
    |-- tm.properties
    +-- tsam.properties