doc/src/060_preInstallations.adoc - mdmbl/org.eclipse.mdm - Git at Google

 == Preconditions and required installations

 === Glassfish

 **Supported versions:**

 **Glassfish, Version 4.1.2**

 * Download Full Platform: +
 https://javaee.github.io/glassfish/download
 * Administration-Guide: +
  https://javaee.github.io/glassfish/doc/4.0/administration-guide.pdf
 * Security-Guide: +
 https://javaee.github.io/glassfish/doc/4.0/security-guide.pdf
 * Some patches are necessary. Refer to this chapter for patching glassfish. [ TODO link to chapter]

 **Glassfish, Version5.1.0**

 * Full Platform from https://projects.eclipse.org/projects/ee4j.glassfish/downloads
 * Deployment with Glassfish Administration Console is not possible, because of a Glassfish Bug: 545170 - "Archive Path is NULL" when deploying from GUI +
 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=545170)
 * Administration-Guide: +
 https://javaee.github.io/glassfish/doc/5.0/administration-guide.pdf
 + Security-Guide: +
 https://javaee.github.io/glassfish/doc/5.0/security-guide.pdf

 **Installation:**

 * Unzip the file into a directory without spaces (recommended).
 * Test it:
 ** change to the glassfish-root directory
 ** invoke `./glassfish/bin/asadmin start-domain`
 ** change to your browser
 ** URL localhost:8080 should show you a welcome page
 ** URL localhost:4848 should show you the admin page
 ** Note: if you need to change the default ports 8080 or 4848 please see the glassfish documentation


 === Database for the User Preference Service
 The Preference service stores its data to a relational database. The database connection is looked up by JNDI and the JNDI name and other database relevant parameters are specified in +src/main/resources/META-INF/persistence.xml+. The default JNDI name for the JDBC resource is set to jdbc/openMDM.

 For the User Preference Service you need a database with a schema “openMDM”.

 Note: “OPENMDM” is the default schema name, it can be changed in the file:
 `/org.eclipse.mdm.nucleus/org.eclipse.mdm.preferences/src/main/resources/META-INF/persistence.xml`

 For activating the change, the artefacts have to be rebuilt.

 ==== Apache Derby Database
 The Glassfish Application Server has included the Derby libraries.

 **Create database and tables:**

 * Change to your <glassfish_root> directory. +
 * Start the database:

  <glassfish_root>$ ./glassfish/bin/asadmin start-database

  * Start the ij Tool (http://db.apache.org/derby/papers/DerbyTut/ij_intro.html):

  <glassfish_root>$ java -jar ./javadb/lib/derbyrun.jar ij

 * Create database with default name “openMDM”

  ij> CONNECT 'jdbc:derby://localhost:1527/openMDM;create=true';

 * Create the table “preference”

  ij> CREATE TABLE OPENMDM.PREFERENCE (ID BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL, keyCol VARCHAR(255), SOURCE VARCHAR(255), username VARCHAR(255), valueCol CLOB(2147483647) NOT NULL, PRIMARY KEY (ID));

 * Add constraints

  ij> ALTER TABLE OPENMDM.PREFERENCE ADD CONSTRAINT UNQ_PREFERENCE_0 UNIQUE (source, username, keyCol);

 * Check table:

  ij> SELECT * FROM OPENMDM.PREFERENCE;

 * Create the table “system_process” (since 5.2.0M1):

   ij> CREATE TABLE OPENMDM.SYSTEM_PROCESS (ID BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL, process_id VARCHAR(255), process_key VARCHAR(255), last_locked BIGINT, PRIMARY KEY (ID));

 * close ij

  ij> exit;

 * Stop database.

  <glassfish_root>$ ./bin/asadmin stop-database


 ==== Other Database Products

 There is also the possibility to use other database products. For Postgres DB you will find the according sql scripts after the nucleus build in the following directory: +
 `$workspace/org.eclipse.mdm.nucleus/build/distributions/schema/org.eclipse.mdm.preferences`.Other database products supported by EclipseLink may also work, but are neither tested nor supported by the mdmbl project.


 ==== Configure JDBC for the User Preference Service DB

 For the User Preference Sevice DB configure JDBC resource and its dependent JDBC Connection Pool. It has to be created and configured through asadmin command line tool.
 (the glassfish web administration console is not recommended, as it is pretty buggy).

 **Description for the Derby Database with defaultname “openMDM”:**

 . Start domain, database and admin-tool:

  <glassfish_root>$ ./bin/asadmin start-domain
  <glassfish_root>$ ./bin/asadmin start-database
  <glassfish_root>$ ./bin/asadmin


 . Create JDBC Connection Pool “openMDM” with
 User, Password and DatabaseName “openMDM”:

  asadmin> create-jdbc-connection-pool --datasourceclassname                 org.apache.derby.jdbc.ClientDataSource --restype javax.sql.DataSource --property password=openMDM:user=openMDM:serverName=localhost:databaseName=openMDM:connectionAttributes=\;create\\=true openMDM


 . Check  JDBC Connection Pool:

   asadmin>ping-connection-pool
   asadmin>list-jdbc-connection-pools”

 . Create JDBC Resource:

  asadmin> create-jdbc-resource --connectionpoolid openMDM jdbc/openMDM


 . Check  JDBC Resource:

   asadmin>list-jdbc-resources

 . Stop domain, database:

  <glassfish_root>$ ./bin/asadmin stop-domain domain1
  <glassfish_root>$ ./bin/asadmin stop-database

 === ElasticSearch

 Download ElasticSearch 7 for openMDM 5.1.0++: +
 https://www.elastic.co/products/elasticsearch
 or +
 https://www.elastic.co/de/downloads/past-releases#elasticsearch

 For openMDM 5.0.x and 5.1.Mx use version 2.x., e.g.
 https://www.elastic.co/de/downloads/past-releases/elasticsearch-2-4-2

 For testing purpose, it can be simply started by executing:

  <elasticsearch_root>$ ./bin/elasticsearch

 === Database for ODS-Server

 The database product is dependent of the ODS Server you use. To start an ODS Server you need a loaded ASAM ODS Application Model in the DB.


 **Embedded Apache Derby Database and Peak ODS Server:**

 If you use a Peak ODS Server from Peak Solutions GmbH:
 they provide an embedded demo Derby Database with an Application Model and Data. Follow their instructions.


 === ODS Server
 ASAM 	ODS-Server e.g. from

 * Peak Solution: 		http://www.peak-solution.de/de/produkte-leistungen/versuchs-messdatenmanagement/softwareloesungen/peak-ods-server/
 * HiQSoft:
 https://www.highqsoft.com/de/avalon-asam-ods-server/
 * or another compliant data source (e.g. PAK adapter)
 * Get a (test) license from the vendors and follow the installation instructions.
 * If you already imported an Application Model to your database and database is running, then the ODS Server should start.

 **Notes for running a Peak ODS Server: **

 * You need two additional plugins copy them to  $odsserver_root/plugins:
 ** Put peakcorbafileserver-VERSION.jar into plugins
 ** Put notification-plugin-VERSION.jar into plugins
 * Configure parameters in $odsserver_root/cfg/server.properties:
 ** Add the following line to enable the notification service: JMS_FORWARDER.PORT=8089
 ** The Peak ODS Server can run its own ORB daemon. Just leave the following parameter blank: NAMESERVICE=
 * Use the Peak demo Derby DB (MDMNVH DB) in embedded mode, the database starts automatically with the Peak ODS Server startup. +
 Username and password are the same must be the name of the schema.

  DB_DRIVER = DERBY_EMBEDDED
  DB_URL = jdbc:derby:/<path_to_MDMNVH_DerbyDB>/MDMNVH;create=false
  DB_USER = MDMNVH
  DB_PASSWORD = MDMNV
	== Preconditions and required installations

	=== Glassfish

	Supported versions:

	Glassfish, Version 4.1.2

	* Download Full Platform: +
	https://javaee.github.io/glassfish/download
	* Administration-Guide: +
	https://javaee.github.io/glassfish/doc/4.0/administration-guide.pdf
	* Security-Guide: +
	https://javaee.github.io/glassfish/doc/4.0/security-guide.pdf
	* Some patches are necessary. Refer to this chapter for patching glassfish. [ TODO link to chapter]

	Glassfish, Version5.1.0

	* Full Platform from https://projects.eclipse.org/projects/ee4j.glassfish/downloads
	* Deployment with Glassfish Administration Console is not possible, because of a Glassfish Bug: 545170 - "Archive Path is NULL" when deploying from GUI +
	(https://bugs.eclipse.org/bugs/show_bug.cgi?id=545170)
	* Administration-Guide: +
	https://javaee.github.io/glassfish/doc/5.0/administration-guide.pdf
	+ Security-Guide: +
	https://javaee.github.io/glassfish/doc/5.0/security-guide.pdf

	Installation:

	* Unzip the file into a directory without spaces (recommended).
	* Test it:
	** change to the glassfish-root directory
	** invoke `./glassfish/bin/asadmin start-domain`
	** change to your browser
	** URL localhost:8080 should show you a welcome page
	** URL localhost:4848 should show you the admin page
	** Note: if you need to change the default ports 8080 or 4848 please see the glassfish documentation


	=== Database for the User Preference Service
	The Preference service stores its data to a relational database. The database connection is looked up by JNDI and the JNDI name and other database relevant parameters are specified in +src/main/resources/META-INF/persistence.xml+. The default JNDI name for the JDBC resource is set to jdbc/openMDM.

	For the User Preference Service you need a database with a schema “openMDM”.

	Note: “OPENMDM” is the default schema name, it can be changed in the file:
	`/org.eclipse.mdm.nucleus/org.eclipse.mdm.preferences/src/main/resources/META-INF/persistence.xml`

	For activating the change, the artefacts have to be rebuilt.

	==== Apache Derby Database
	The Glassfish Application Server has included the Derby libraries.

	Create database and tables:

	* Change to your <glassfish_root> directory. +
	* Start the database:

	<glassfish_root>$ ./glassfish/bin/asadmin start-database

	* Start the ij Tool (http://db.apache.org/derby/papers/DerbyTut/ij_intro.html):

	<glassfish_root>$ java -jar ./javadb/lib/derbyrun.jar ij

	* Create database with default name “openMDM”

	ij> CONNECT 'jdbc:derby://localhost:1527/openMDM;create=true';

	* Create the table “preference”

	ij> CREATE TABLE OPENMDM.PREFERENCE (ID BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL, keyCol VARCHAR(255), SOURCE VARCHAR(255), username VARCHAR(255), valueCol CLOB(2147483647) NOT NULL, PRIMARY KEY (ID));

	* Add constraints

	ij> ALTER TABLE OPENMDM.PREFERENCE ADD CONSTRAINT UNQ_PREFERENCE_0 UNIQUE (source, username, keyCol);

	* Check table:

	ij> SELECT * FROM OPENMDM.PREFERENCE;

	* Create the table “system_process” (since 5.2.0M1):

	ij> CREATE TABLE OPENMDM.SYSTEM_PROCESS (ID BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL, process_id VARCHAR(255), process_key VARCHAR(255), last_locked BIGINT, PRIMARY KEY (ID));

	* close ij

	ij> exit;

	* Stop database.

	<glassfish_root>$ ./bin/asadmin stop-database


	==== Other Database Products

	There is also the possibility to use other database products. For Postgres DB you will find the according sql scripts after the nucleus build in the following directory: +
	`$workspace/org.eclipse.mdm.nucleus/build/distributions/schema/org.eclipse.mdm.preferences`.Other database products supported by EclipseLink may also work, but are neither tested nor supported by the mdmbl project.


	==== Configure JDBC for the User Preference Service DB

	For the User Preference Sevice DB configure JDBC resource and its dependent JDBC Connection Pool. It has to be created and configured through asadmin command line tool.
	(the glassfish web administration console is not recommended, as it is pretty buggy).

	Description for the Derby Database with defaultname “openMDM”:

	. Start domain, database and admin-tool:

	<glassfish_root>$ ./bin/asadmin start-domain
	<glassfish_root>$ ./bin/asadmin start-database
	<glassfish_root>$ ./bin/asadmin


	. Create JDBC Connection Pool “openMDM” with
	User, Password and DatabaseName “openMDM”:

	asadmin> create-jdbc-connection-pool --datasourceclassname org.apache.derby.jdbc.ClientDataSource --restype javax.sql.DataSource --property password=openMDM:user=openMDM:serverName=localhost:databaseName=openMDM:connectionAttributes=\;create\\=true openMDM


	. Check JDBC Connection Pool:

	asadmin>ping-connection-pool
	asadmin>list-jdbc-connection-pools”

	. Create JDBC Resource:

	asadmin> create-jdbc-resource --connectionpoolid openMDM jdbc/openMDM


	. Check JDBC Resource:

	asadmin>list-jdbc-resources

	. Stop domain, database:

	<glassfish_root>$ ./bin/asadmin stop-domain domain1
	<glassfish_root>$ ./bin/asadmin stop-database

	=== ElasticSearch

	Download ElasticSearch 7 for openMDM 5.1.0++: +
	https://www.elastic.co/products/elasticsearch
	or +
	https://www.elastic.co/de/downloads/past-releases#elasticsearch

	For openMDM 5.0.x and 5.1.Mx use version 2.x., e.g.
	https://www.elastic.co/de/downloads/past-releases/elasticsearch-2-4-2

	For testing purpose, it can be simply started by executing:

	<elasticsearch_root>$ ./bin/elasticsearch

	=== Database for ODS-Server

	The database product is dependent of the ODS Server you use. To start an ODS Server you need a loaded ASAM ODS Application Model in the DB.


	Embedded Apache Derby Database and Peak ODS Server:

	If you use a Peak ODS Server from Peak Solutions GmbH:
	they provide an embedded demo Derby Database with an Application Model and Data. Follow their instructions.


	=== ODS Server
	ASAM ODS-Server e.g. from

	* Peak Solution: http://www.peak-solution.de/de/produkte-leistungen/versuchs-messdatenmanagement/softwareloesungen/peak-ods-server/
	* HiQSoft:
	https://www.highqsoft.com/de/avalon-asam-ods-server/
	* or another compliant data source (e.g. PAK adapter)
	* Get a (test) license from the vendors and follow the installation instructions.
	* If you already imported an Application Model to your database and database is running, then the ODS Server should start.

	Notes for running a Peak ODS Server:

	* You need two additional plugins copy them to $odsserver_root/plugins:
	** Put peakcorbafileserver-VERSION.jar into plugins
	** Put notification-plugin-VERSION.jar into plugins
	* Configure parameters in $odsserver_root/cfg/server.properties:
	** Add the following line to enable the notification service: JMS_FORWARDER.PORT=8089
	** The Peak ODS Server can run its own ORB daemon. Just leave the following parameter blank: NAMESERVICE=
	* Use the Peak demo Derby DB (MDMNVH DB) in embedded mode, the database starts automatically with the Peak ODS Server startup. +
	Username and password are the same must be the name of the schema.

	DB_DRIVER = DERBY_EMBEDDED
	DB_URL = jdbc:derby:/<path_to_MDMNVH_DerbyDB>/MDMNVH;create=false
	DB_USER = MDMNVH
	DB_PASSWORD = MDMNV