Installation instructions

The purpose of this document is to provide an overview of how to manage the installation of the Jems service and its components. The following open source software needs to be installed as a prerequisite for the Jems service to be used. Interact will provide a resource to download the latest version of the Jems package.

Target group

This document addresses, in particular, IT administrators and operators, as well as IT system architects.

Prerequisites

Components requirements

It is required to install the following OS and components listed below for the successful usage of the Jems service

Linux platform (Kernel 4.x or higher)
OpenJDK Runtime Environment 11
MariaDB 10.6.12
Elasticsearch 7.17.9
MinIO RELEASE.2021-08-05T22-01-19Z

MariaDB is critical component for Jems service, which is required for a proper feature functionalities which are not supported by MySQL!

There are two possible ways of installing the components needed for Jems:

[Manual] Service administrator installs components (see 3.1)

[Automatic] Docker Compose installs all components at once (see 3.2)

Deliverable

Interact delivers a ZIP file containing:

A precompiled Java application in Jar format
A Docker Compose script which optionally allows automatic installation
Addons folder containing standard Addons implementations

Structure:

CODE

ReleasXXXXX.zip
│   docker-compose.yml
│   jems-server.jar
│
└───addons
        jems-standard-plugin-X.X.X-SNAPSHOT.jar

Installation instructions

Manual installation of the components

It is recommended to follow the official technical documentation from a package provider to install the required components successfully. If you want to use an already existing environment which potentially could have installed one of the components mentioned above, it is strongly recommended to follow the instructions from the components provider in order to avoid collisions and cross dependencies.

Please find below the component parameters required for services startup. Please note: If you use different configuration values from the default ones, you should refer to the extended Jems configuration section 3.4.

MariaDB component configuration parameters:

Parameter	Default value
character-set-server	utf8mb4
collation-server	utf8mb4_unicode_ci
port number	3306
MYSQL_DATABASE	jemsdb
MYSQL_ROOT_PASSWORD	Mariadb@2020

Elasticsearch component configuration parameters:

Parameter	Default value
port number	9200
discovery.type	single-node

In case you need secure connection between Jems and ES:

enable xpack.security.enabled: true and setting default password for elastic user by environment variable e.g. ELASTIC_PASSWORD=[your_password] when starting ElasticSearch
Jems will use this user, but you need to inform him/her about your password by setting environment variable AUDIT_ELASTICSEARCH_PASSWOR=[your_password] or alternatively start with -Daudit-service.password=[your_password]
in case you use Docker - before proceeding with this make sure your volumes are explicitly specified
- if they are not specified, changes in configuration might result into creating new volumes and therefore causing loss of all your audits

CODE

  audit-database:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.9
    container_name: audit-database
#    volumes:
#      - [YOUR/PATH/HERE]:/usr/share/elasticsearch/data
    ports:
      - '9200:9200'
    environment:
      - discovery.type=single-node
      - "ES_JAVA_OPTS=-Xms2g -Xmx2g"
      - xpack.security.enabled=true
      - "ELASTIC_PASSWORD=Elastic@2020"

Minio component configuration parameters:

Parameter	Default value
port number	9000
MINIO_ACCESS_KEY	jemsminio
MINIO_SECRET_KEY	Minio@2020

Installation of the components with Docker Compose

Optionally, a Docker Compose script is provided to install and configure the components automatically.

Every Jems service package includes a docker-compose.yml file, which contains instructions to set up the components automatically.

Please get in touch with the Docker Compose package provider to clarify the prerequisites for using Docker Compose and how to manage the installation.

The only limitation, in this case, is that all components are deployed on the same virtual server.

Jems service installation

After successful installation of the components, you can start the Jems service installation and configuration.

It is recommended to setup Jems as a system service, which starts automatically on a system startup.

This is default template, Parameters relevant for this template and example are located below.

Service configuration example (/etc/systemd/system/jems.service)

[Unit]

Description=Jems service

[Service]

WorkingDirectory=/home/jems

ExecStart=/usr/bin/java -Dloader.path=/home/jems/addons -jar /home/jems/jems-server.jar

User=root

Type=simple

Restart=on-failure

RestartSec=10

[Install]

WantedBy=multi-user.target

Due to high number of parameters, the usage of a script might be desirable, see follow example:

CODE

#!/bin/sh

current_time=$(date "+%Y-%m-%d-%H%M")
logFileName=logs/jems-$current_time.log

/usr/bin/java \
  -Dloader.path=/home/jems/plugins \
  -Dserver.port=8083 \
  -Dspring.datasource.url=jdbc:mariadb://localhost:3308/jemsdb \
  -Dspring.datasource.password=mariadb-password \
  -Daudit-service.enabled=true \
  -Daudit-service.url-and-port=localhost:9202 \
  -Daudit-service.password=elastic-password \
  -Dinfo.accessibility-statement-url=https://helpdesk.interreg.eu/staticdocumentation/accessibility.html \
  -Dspring.mail.host=mail.provider.eu \
  -Dspring.mail.port=587 \
  -Dspring.mail.username=info@interreg.eu \
  -Dspring.mail.password=mail-password \
  -Dspring.mail.protocol=smtp \
  -Dspring.mail.properties.mail.smtp.auth=true \
  -Dspring.mail.properties.mail.smtp.connectiontimeout=25000 \
  -Dspring.mail.properties.mail.smtp.timeout=25000 \
  -Dspring.mail.properties.mail.smtp.writetimeout=25000 \
  -Dspring.mail.properties.mail.smtp.starttls.enable=true \
  -Dapp.notification.mail.enabled=true \
  -Dapp.notification.mail.sender=noreply-jems@interreg.eu \
  -Dapp.notification.mail.bcc-list= \
  -Dapp.server-url=https://interreg.eu \
  -Dminio-storage.endpoint=http://localhost:9004 \
  -Dminio-storage.accessKey=jemsminio \
  -Dminio-storage.secretKey=minio-password \
  -Dlogging.file.name=$logFileName \
  -jar /home/jems/jems-server-latest.jar

Jems service operation system permissions

Ensure that the user under which the Jems service is running in the OS, has a valid permissions and write permissions for the folder where Jems service is located.

Extended Jems configuration steps

As an option, it is possible to setup Jems as a system service with additional startup parameters.

These parameters allow you to specify configuration values for services on which Jems is dependent. Please find below how the optional parameters should be specified on service startup.

Add-on parameter

Parameter

Recommended value

Add-ons location folder

-Dloader.path=addons

Ex: If folder where your Jems server located is /home/jems, then recommended value should be:

-Dloader.path=/home/jems/addons

Additional startup parameters

Below you can find startup parameters with recommended values

Note: This values are taken by default, then Jems starts without parameters

Parameter	Recommended value
Server port number	--server.port=8080
Type of certificate (If Jems runs directly on HTTPS)	--server.ssl.keyStoreType=PKCS12
Certificate path (If Jems runs directly on HTTPS)	--server.ssl.key-store=file:/home/user/SSL/certificate.pfx
Certificate password (If Jems runs directly on HTTPS)	--server.ssl.key-store-password=<certificatePassword>
Database connection sting	--spring.datasource.url=jdbc:mariadb://localhost:3306/jemsdb
Database user	--spring.datasource.username=JemsDBuser
Database secret	--spring.datasource.password=Mariadb@2020
Elastic search status	--audit-service.enabled=true
Elastic search host	--audit-service.url-and-port=localhost:9200
Minio host	--minio-storage.endpoint=http://localhost:9000
Minio user name	--minio-storage.accessKey=jemsminio
Minio password	--minio-storage.secretKey=Minio@2020
Enables all --info parameters (see below) future version will be by default	--management.info.env.enabled=true
Helpdesk e-mail	--info.helpdesk-email=info@your.programme.com
Helpdesk URL	--info.helpdesk-url=http://your.programme.com
Accessibility Statement URL	--info.accessibility-statement-url=http://your.programme.com
Terms privacy policy URL	--info.terms-privacy-policy-url=http://your.programme.com
Maximum supported file size	--spring.servlet.multipart.max-file-size=50MB
Session timeout. On user inactivity after time elapsed, user will be automatically logged out.	--server.servlet.session.timeout=60m
Notification service - host name	--spring.mail.host=smtp.your-email-service.com
Notification service - port number	--spring.mail.port=587
Notification service - user name (used for authentication)	--spring.mail.username=username_of_programme@your-emal-service.com
Notification service - user password (used for authentication)	--spring.mail.password=PaSsWoRd_toAccOunt
Notification service - communication protocol (by default should be smtp)	--spring.mail.protocol=smtp
Notification service - authentication flag configuration (true - authentication is required/ false - authentication is not required, you may leave user name and password blank )	--spring.mail.properties.mail.smtp.auth=true
Notification service - connection to host timeout	--spring.mail.properties.mail.smtp.connectiontimeout=25000
Notification service - mail response timeout	--spring.mail.properties.mail.smtp.timeout=25000
Notification service - mail send timeout	--spring.mail.properties.mail.smtp.writetimeout=25000
Notification service - Transport Layer Security (true - Activated / false - deactivated)	--spring.mail.properties.mail.smtp.starttls.enable=true
Notification service - Enable flag, activates entire or deactivates entire notification service (true - Activated / false - Deactivated)	--app.notification.mail.enabled=true
Notification service - Sender email, will be shown for recipient	--app.notification.mail.sender=username_of_programme@your-email-service.com
Notification service - Carbon copy recipients. All outgoing notifications will be duplicated to the list of the mails specified in this property	--app.notification.mail.bcc-list=username_of_programme@your-email-service.com,admin_of_programme@your-email-service.com
Notification service - Service URL, is used in the notification body. Should be used the same service URL as for service itself	--app.server-url=http://programme_URL.xyz
Captcha - It is used for user registration, by default is activated	--app.captcha.enabled = false (deactivates captcha)
Log - Set the level by default is INFO (possible values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL)	--logging.level.org.springframework=WARN (use DEBUG for test environments)
Log - Set exact path for log file, by default all log goes to console output	--logging.file.name=/var/log/jems.log (make sure path exists and is writable to Jems service)
Service configuration example (/etc/systemd/system/jems.service)
[Unit] Description=Jems service [Service] WorkingDirectory=/home/jems ExecStart=/usr/bin/java -Dloader.path=/home/jems/addons -jar /home/jems/jems-server.jar --spring.datasource.url=jdbc:mariadb://localhost:3306/jemsdb --spring.mail.host=smtp.your-emal-service.com --spring.mail.port=587 --spring.mail.username=username_of_programme@your-emal-service.com --spring.mail.password=PaSsWoRd_toAccOunt --spring.mail.protocol=smtp --spring.mail.properties.mail.smtp.auth=true --spring.mail.properties.mail.smtp.connectiontimeout=25000 --spring.mail.properties.mail.smtp.timeout=25000 --spring.mail.properties.mail.smtp.writetimeout=25000 --spring.mail.properties.mail.smtp.starttls.enable=true --app.notification.mail.enabled=true --app.notification.mail.sender=username_of_programme@your-emal-service.com --app.notification.mail.bcc-list=username_of_programme@your-emal-service.com,admin_of_programme@your-emal-service.com --app.server-url=http://programme_URL.interact-eu.net --info.helpdesk-url=https://your.programme.com --info.helpdesk-email=info@your.programme.com User=root Type=simple Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target

First login

By default Jems service contains predefined user with admin privileges.

User name	Password
admin@jems.eu	Jems@2020admin@jems.eu

Please provide this credentials for successful first login.

Do not forget to change password to avoid security issues.