Installation Guide

Morgan Guimard edited this page Mar 16, 2018 · 108 revisions

Introduction

This page covers the installation and configuration of the software required to run the DocDokuPLM application. After that, you could jump to the configuration page.

Prerequisite Software

DocDokuPLM is a Java application, thus you have to install Java JDK version 8 first. To run DocDokuPLM, you also need a JEE 7 Application Server and a database system.

Payara and MySQL 5.7 are good choices but any JEE 7 compliant server works as well as SQLServer, PostGreSQL or Oracle for the RDMS part.

Glassfish and Payara

DocDokuPLM need a Java EE 7 server. The server version depends on the DocDokuPLM version you plan to use. Please use the "server full" edition for 2.0 and 2.5 version.

DocDokuPLM 2.0

This version must be deployed on a Glassfish 4.0 application server. Download Glassfish from official website.

DocDokuPLM 2.5

This version must be deployed on Payara 4.1. You can download it from Payara website.

MySQL

To download MySQL version 5 just follow this link.

Don't forget to copy a version of the JDBC driver, unzip the file and copy the *.jar file (i.e. mysql-connector-java-5.1.25-bin.jar) into {glassfish install dir}/domains/{domainName}/lib folder. By entering apt-get install libmysql-java the jdbc jar file will be copied into /usr/share/java folder. Then create a symbolic link to the lib: ln -s /usr/share/java/mysql-connector-java.jar {glassfish install dir}/domains/{domainName}/lib

LibreOffice

To be able to generate PDF files, we need to download and install LibreOffice version 4 or 5. On Linux system, LibreOffice is provided as a regular package, for example on debian based distrib you can just enter : sudo apt-get install libreoffice.

CAD converter

If you want to setup CAD files converters just follow these instructions.

Elasticsearch Indexer

To allow document search or product part search you will have to install Elasticsearch. Follow these instructions.

Prerequisite Software Configuration

MySQL Configuration

Edit your mysql configuration file (my.cnf) and check that you have enabled INNODB as the default engine, this is the case since version 5.5.

Log into MySQL to create the DocDokuPLM database with the following command: CREATE DATABASE docdokuplm;

Then create the MySQL user for the DocDokuPLM application: GRANT ALL PRIVILEGES ON docdokuplm.* TO 'docdokuplm_user'@'localhost' IDENTIFIED BY 'password';

Of course, you may specify a better password or change localhost to the hostname of the glassfish server if it's not installed on the same machine than MySQL.

Glassfish Configuration

You can either use the preconfigured domain1 domain or create your own domain with the following command line: {glassfish install dir}/bin/asadmin create-domain {domainName};

Then start the glassfish server: {glassfish install dir}/bin/asadmin start-domain {domainName}; and log into the admin console http://localhost:4848 or create domain settings from command line.

JDBC

JDBC Connection Pools

Configure the jdbc connection pool. Go under Resources > JDBC > Connection Pools and click on New. Create your connection pool, you can name it DocDokuPLMPool, for the resource type you have to select javax.sql.ConnectionPoolDataSource and for the Driver Provider Database select MySQL. Then click Next.

Note that, depending on the application server, you may have a long list of parameters. Delete them all, and type only the four ones above. If, for some reasons, you prefer to keep all these parameters, check that the url parameter is valid for JEE conventions and includes the database name at its end. Be careful the url parameter may appear twice (as url and URL).

Select Transaction Isolation = read-committed

Fill now the parameters like that:

databaseName = docdokuplm
serverName = localhost
user = docdokuplm_user
password = {db password}  //The password you enter during the mysql server configuration 

Note also that default MySQL port is 3306, but you may have another configuration (typically 8889 with MAMP on Mac OS). You may so need to add the port configuration:

port = 8889

Finally, save and check your configuration by clicking on Ping.

JDBC Resources

Go under Resources > JDBC > JDBC Resources and create the jdbc resource associated with the DocDokuPLMPool, enter jdbc/docdokuPU as the JNDI name.

Mail

On Resources > JavaMail Sessions, add a mail session with mail/docdokuSMTP for the JNDI name, and fill your mail configuration.

Service HTTP

Now, we need to fine tune the HTTP service in Configurations > server-config > Network Config > Protocols > http-listener-1 > HTTP with the following parameters:

Upload Timeout = disabled
Connection Upload Timeout = -1
Request Timeout = -1

DocDokuPLM properties

One JNDI Custom Resource need to be created in Resources / JNDI / Custom Resources with docdokuplm.config as JNDI name and java.util.Properties as resource type

IMPORTANT: This JNDI resource has to be defined for the application to start

Then some entries need to be added as additional properties:

  • vaultPath : defines the path of uploaded files (/var/lib/docdoku)
  • codebase : defines the base URL used in mails, refers to webapp address (use http://localhost:9001 in default development configuration)
  • digestAlgorithm : optional, defines the digest algorithm used when storing the passwords inside the database (SHA-256, SHA-1...), MD5 is the default value

Security properties

One JNDI Custom Resource need to be created in Resources / JNDI / Custom Resources with auth.config as JNDI name and java.util.Properties as resource type

IMPORTANT: This JNDI resource has to be defined for the application to start

Then some entries need to be added as additional properties:

  • jwt.enabled : enable or disable JWT support (default value is false)
  • jwt.key : your secret password (if not set a key will be randomly generated)
  • session.enabled : enable or disable Cookie support (default value is false)
  • basic.header.enabled : enable or disable Basic Header support (default value is false)

Elasticsearch properties

One JNDI Custom Resource need to be created in Resources / JNDI / Custom Resources with elasticsearch.config as JNDI name and java.util.Properties as resource type

IMPORTANT: This JNDI resource has to be defined for the application to start

Then some entries need to be added as additional properties:

  • serverUri : defines the Elasticsearch server uri, i.e. the HTTP REST endpoint (http://localhost:9200)
  • number_of_shards : defines the Elasticsearch number of shards (5)
  • auto_expand_replicas : defines the Elasticsearch auto expand replicas (0-3)
  • number_of_replicas : defines the Elasticsearch number of replicas (0)
  • username : optional, defines the username to use to authenticate the HTTP requests (xpack default is elastic).
  • password : optional, defines the password to use to authenticate the HTTP requests (xpack default is changeme).

If you use Amazon Elasticsearch Service, the following parameters must also be specified:

  • awsService : defines the aws service parameter required for the signing process (es)
  • awsRegion : defines the aws region parameter required for the signing process (eu-west-1)
  • awsAccessKey : defines the AWS Access key to use to sign the requests
  • awsSecretKey : defines the AWS Secret key to use to sign the requests

LibreOffice

One JNDI Custom Resource need to be created in Resources / JNDI / Custom Resources with office.config as JNDI name and java.util.Properties as resource type

IMPORTANT: This JNDI resource has to be defined for the application to start

Then some entries need to be added as additional properties:

  • office_home : defines the path of LibreOffice home directory (/usr/lib/libreoffice)
  • office_port : defines the port used by LibreOffice (8100)

JVM

In Configurations > server-config > JVM Settings, in the tab JVM Option, you need to add the option -Dfile.encoding=UTF-8

Database encryption

Some sensitive data need to be encrypted in the database.

Generate a keystore or use an existing one.

keytool -genseckey -storetype JCEKS -keyalg AES -keysize 256 -keystore dplm.jceks

One JNDI Custom Resource need to be created in Resources / JNDI / Custom Resources with security.config as JNDI name and java.util.Properties as resource type

IMPORTANT: This JNDI resource has to be defined for the application to start

Then some entries need to be added as additional properties:

  • keystoreLocation : defines the path of the keystore file
  • keystorePass : password for keystore file
  • keyAlias : key alias name
  • keystoreType : keystore type, default is JCEKS
  • keyPass : key password (default is value from the keystorePass entry)

Asadmin command lines

All configurations can be done with the asadmin command

## Custom resources

./asadmin create-custom-resource \
 --restype java.util.Properties \
 --factoryclass org.glassfish.resources.custom.factory.PropertiesFactory \
 --property="" \
  docdokuplm.config

./asadmin create-custom-resource \
 --restype java.util.Properties \
 --factoryclass org.glassfish.resources.custom.factory.PropertiesFactory \
 --property="" \
 auth.config

    ./asadmin create-custom-resource \
 --restype java.util.Properties \
 --factoryclass org.glassfish.resources.custom.factory.PropertiesFactory \
 --property="" \
 security.config

## Elasticsearch config

./asadmin create-custom-resource \
 --restype java.util.Properties \
 --factoryclass org.glassfish.resources.custom.factory.PropertiesFactory \
 --property="" \
 elasticsearch.config

## Office config

./asadmin create-custom-resource \
 --restype java.util.Properties \
 --factoryclass org.glassfish.resources.custom.factory.PropertiesFactory \
 --property="" \
 office.config

## JDBC Connection pool

./asadmin create-jdbc-connection-pool \
 --restype javax.sql.ConnectionPoolDataSource \
 --datasourceclassname com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource \
 --property="" \
 DocDokuPLMPool

## JDBC PU

./asadmin create-jdbc-resource \
 --connectionpoolid DocDokuPLMPool jdbc/docdokuPU

## JVM options

./asadmin create-jvm-options \
 -Dfile.encoding=UTF-8

## JavaMail
# Create and configure the resource with your mail configuration.
# https://docs.oracle.com/cd/E19798-01/821-1758/create-javamail-resource-1/index.html

./asadmin create-javamail-resource \
 --mailhost localhost \
 --mailuser myUser \
 --fromaddress myUser@localhost \
 mail/docdokuSMTP
 
## Http Listener settings

./asadmin set server.network-config.protocols.protocol.http-listener-1.http.upload-timeout-enabled=false
./asadmin set server.network-config.protocols.protocol.http-listener-1.http.connection-upload-timeout-millis=-1

## Set your configuration

./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.databaseName=
./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.serverName=
./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.user=
./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.password=

./asadmin set resources.custom-resource.docdokuplm.config.property.vaultPath=
./asadmin set resources.custom-resource.docdokuplm.config.property.codebase=

./asadmin set resources.custom-resource.auth.config.property."jwt\.enabled"=
./asadmin set resources.custom-resource.auth.config.property."jwt\.key"=
./asadmin set resources.custom-resource.auth.config.property."session\.enabled"=
./asadmin set resources.custom-resource.auth.config.property."basic\.header\.enabled"=

./asadmin set resources.custom-resource.elasticsearch.config.property.serverUri=
./asadmin set resources.custom-resource.elasticsearch.config.property.number_of_shards=
./asadmin set resources.custom-resource.elasticsearch.config.property.auto_expand_replicas=
./asadmin set resources.custom-resource.elasticsearch.config.property.number_of_replicas=
./asadmin set resources.custom-resource.elasticsearch.config.property.password=
./asadmin set resources.custom-resource.elasticsearch.config.property.username=
./asadmin set resources.custom-resource.elasticsearch.config.property.awsService=
./asadmin set resources.custom-resource.elasticsearch.config.property.awsRegion=
./asadmin set resources.custom-resource.elasticsearch.config.property.awsAccessKey=
./asadmin set resources.custom-resource.elasticsearch.config.property.awsSecretKey=

./asadmin set resources.custom-resource.office.config.property.office_home=
./asadmin set resources.custom-resource.office.config.property.office_port=

./asadmin set resources.custom-resource.security.config.property.keystoreLocation=
./asadmin set resources.custom-resource.security.config.property.keystorePass=
./asadmin set resources.custom-resource.security.config.property.keyAlias=
./asadmin set resources.custom-resource.security.config.property.keystoreType=
./asadmin set resources.custom-resource.security.config.property.keyPass=

## Sample configuration - adapt it to your needs

#./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.databaseName=docdokuplm
#./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.serverName=localhost
#./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.user=docdoku_dbuser
#./asadmin set resources.jdbc-connection-pool.DocDokuPLMPool.property.password=password

#./asadmin set resources.custom-resource.docdokuplm.config.property.vaultPath=/var/lib/docdoku/vault
#./asadmin set resources.custom-resource.docdokuplm.config.property.codebase=http://localhost:8080

#./asadmin set resources.custom-resource.auth.config.property."jwt\.enabled"=true
#./asadmin set resources.custom-resource.auth.config.property."jwt\.key"=MyVerySercretPhrase
#./asadmin set resources.custom-resource.auth.config.property."session\.enabled"=false
#./asadmin set resources.custom-resource.auth.config.property."basic\.header\.enabled"=false

#./asadmin set resources.custom-resource.elasticsearch.config.property.serverUri=http://localhost:9200
#./asadmin set resources.custom-resource.elasticsearch.config.property.number_of_shards=5
#./asadmin set resources.custom-resource.elasticsearch.config.property.auto_expand_replicas="0-3"
#./asadmin set resources.custom-resource.elasticsearch.config.property.number_of_replicas=0
#./asadmin set resources.custom-resource.elasticsearch.config.property.password=
#./asadmin set resources.custom-resource.elasticsearch.config.property.username=
#./asadmin set resources.custom-resource.elasticsearch.config.property.awsService=es
#./asadmin set resources.custom-resource.elasticsearch.config.property.awsRegion=eu-west-1
#./asadmin set resources.custom-resource.elasticsearch.config.property.awsAccessKey=MyAwsKey
#./asadmin set resources.custom-resource.elasticsearch.config.property.awsSecretKey=MyAwsSecret

#./asadmin set resources.custom-resource.office.config.property.office_home=/usr/lib/libreoffice
#./asadmin set resources.custom-resource.office.config.property.office_port=8100

#./asadmin set resources.custom-resource.security.config.property.keystoreLocation=/path/to/dplm.jceks
#./asadmin set resources.custom-resource.security.config.property.keystorePass=MySecretPassword
#./asadmin set resources.custom-resource.security.config.property.keyAlias=mykey
#./asadmin set resources.custom-resource.security.config.property.keystoreType=JCEKS
#./asadmin set resources.custom-resource.security.config.property.keyPass=MySecretPassword

Software Configuration & Installation

Once you are done with the installation of prerequisite software, jump to the configuration page.