Install a node on Linux


Hardware prerequisites

Make sure you've checked the Hardware prerequisites before you start configuring your server.

Mandatory prerequisites

Here is the list of the mandatory prerequisites; if they're not met, the node will refuse to start:

  • at least 2 CPU cores on the server
  • a 64-bits operating system
  • an Oracle Java 8 64-bits JVM — provided by the node itself but can be changed
  • at least as much physical memory than the memory configured for the JVMthe JVM cannot use more memory than available RAM
  • for user limits on the operating system:
    • at least 65536 user processes
    • at least 65536 opened files
    • unlimited usage of physical and virtual memory

System prerequisites

A node currently supports the following software prerequisites:

  • 64-bit Linux Operating System:
    • Red Hat Enterprise Linux: 5.x6.x, 7.x

      For Red Hat EL 7, avoid kernel 3.10.0-123.el7 as there is a bug that is seriously affecting Axway Decision Insight.

      Kernel panics can happen (see 1127947 on bugzilla.redhat.com).

      Install a later kernel version or patch this version with patch level >= 3.10.0-123.20.1.el7.

    • Ubuntu: 14 LTS, 16 LTS

      For Ubuntu 14 LTS, avoid kernels 3.13 to 3.15.4 as there is a bug in the Linux kernel shipped with some versions of Ubuntu (see https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1323165).

      You may want to upgrade the operating system to fix it. 

    • SUSE: 11, 12
    • Oracle Linux: 6.x, 7.x
    • Amazon Linux distribution
    • Microsoft Azure Linux distribution

Configuration prerequisites

Please check the following configurations have been properly applied to your environment:

Accounts

Account Required abilities
<Decision Insight administration account>
  • Permissions

    Directory Permissions
    <install directory> read, write, execute

    <working directory>

    read, write, execute

    <logging directory>

    read, write, execute
<Decision Insight execution account>
  • Permissions

    Directory Permissions
    <install directory> read, execute
    <working directory> read, write, execute
    <logging directory> read, write, execute
<System administration account>
  • Register a service
  • Update system configuration files such as /etc/security/limits.conf

<install directory> is the directory where the node will be installed.

<working directory> is the directory where the node will write its data (by default, <working directory> is <install directory>/var).

<logging directory> is the directory where the node logs will be stored (by default, <logging directory> is <working directory>/log).

NTP

Server clock must be synchronized with an NTP server.

When running in a virtual environment, is it recommended to configure NTP at the hypervisor level and to install "tools" in the virtual machine in order that it has a "stable" clock.

System-wide resources limits tuning

On all Linux operating systems, you must ensure that system-wide resources limits are adequate. More specifically, check the following parameters:

Name Name in configuration file limits.conf Description Required value
max number of open file descriptors nofile Maximum number of files (sockets included) a process can open >= 65536
max user processes nproc Maximum number of processes (threads included) a single user can have >= 65536
max memory size rss Maximum amount of memory a process can take unlimited
virtual memory as Maximum amount of virtual memory a process can take unlimited

You can see the current configuration with ulimit -a:

core file size          (blocks, -c) 0
data seg size           (kbytes, -d) unlimited
scheduling priority             (-e) 0
file size               (blocks, -f) unlimited
pending signals                 (-i) 513157
max locked memory       (kbytes, -l) 64
max memory size         (kbytes, -m) unlimited
open files                      (-n) 63336
pipe size            (512 bytes, -p) 8
POSIX message queues     (bytes, -q) 819200
real-time priority              (-r) 0
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 65536
virtual memory          (kbytes, -v) unlimited
file locks                      (-x) unlimited

To change these parameters, edit the /etc/security/limits.conf  configuration file by adding the following lines:

  • For Red Hat Enterprise Linux

    /etc/security/limits.conf
    <Decision Insight execution account> soft nproc 65536
    <Decision Insight execution account> hard nproc 65536
    <Decision Insight execution account> soft nofile 65536
    <Decision Insight execution account> hard nofile 65536
  • For Ubuntu or Amazon Linux distribution

    /etc/security/limits.conf
    <Decision Insight execution account> soft nofile 65536
    <Decision Insight execution account> hard nofile 65536
  • For SUSE

    /etc/security/limits.conf
    <Decision Insight execution account> soft nproc 65536
    <Decision Insight execution account> hard nproc 65536
    <Decision Insight execution account> soft nofile 65536
    <Decision Insight execution account> hard nofile 65536
    <Decision Insight execution account> soft rss unlimited
    <Decision Insight execution account> hard rss unlimited
    <Decision Insight execution account> soft as unlimited
    <Decision Insight execution account> hard as unlimited

For more information on how to change these parameters temporarily or permanently, see:


The node logs the effective limits during the startup so you can verify that the settings are correctly applied. If the values are not correct, the node will not start and you must update your OS configuration in order to fulfill the requirements

2016-11-23 17:40:13,829 [FelixStartLevel] INFO platform - Reading process OS limits from /proc/16707/limits
2016-11-23 17:40:13,829 [FelixStartLevel] INFO platform - --------------------------------------------------------------------------------
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Limit                     Soft Limit           Hard Limit           Units
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max cpu time              unlimited            unlimited            seconds
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max file size             unlimited            unlimited            bytes
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max data size             unlimited            unlimited            bytes
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max stack size            8388608              unlimited            bytes
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max core file size        0                    unlimited            bytes
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max resident set          unlimited            unlimited            bytes
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max processes             524288               1048576              processes
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max open files            1048576              1048576              files
2016-11-23 17:40:13,834 [FelixStartLevel] INFO platform - Max locked memory         65536                65536                bytes
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - Max address space         unlimited            unlimited            bytes
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - Max file locks            unlimited            unlimited            locks
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - Max pending signals       257439               257439               signals
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - Max msgqueue size         819200               819200               bytes
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - Max nice priority         0                    0
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - Max realtime priority     0                    0
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - Max realtime timeout      unlimited            unlimited            us
2016-11-23 17:40:13,835 [FelixStartLevel] INFO platform - --------------------------------------------------------------------------------

Installation prerequisites

  • A valid installer (DecisionInsight_2.0.0_Install_linux-x86-64_BNXXXXXXXXXX.sh) with execute permission granted  (chmod +x DecisionInsight_2.0.0_Install_linux-x86-64_BNXXXXXXXXXX.sh)

    Installers can be downloaded from Axway Sphere or from Decision Insight downloads and release notes

  • A valid license file provided by Axway

Install a node

Using the graphical mode

Launch  the installer

To launch the installer in graphical mode, you can either:

  • Double-click on the installer.

  • Launch the installer using the command line interface.

    ./DecisionInsight_2.0.0_Install_linux-x86-64_BNXXXXXXXXXX.sh

Follow the installation steps

Step 1 : Overall information

Once you have successfully launched the installer on your machine, the installer welcome page is displayed. Click Next.

Step 2 : License agreement

Accept the software license agreement and click Next.

Step 3 : Destination directory

Select an installation path that fulfills the following prerequisites:

  • <Decision Insight administration account> must have full access.
  • <Decision Insight execution account> must have read and execute permissions.

Step 4 : Node settings

Enter the following information:

Time zone — Represents a time zone offset.

It can be filled either by using an ID or the GMT format.

  • For a list of time zone IDs, you can consult List_of_tz_database_time_zones (wikipedia). For example, the time zone ID for the U.S. Pacific Time zone is "America/Los_Angeles". 
  • The GMT format must follow this pattern GMT[+-]00:00., For instance, GMT+01:10 mean one hour ten minutes ahead of GMT. This is not the recommended way to specify a time zone with DST.

Storage starting date — YYYY-MM-DD format, by default 1 month ago.

For a better performance of the platform, this value should be as close as possible to the date of the oldest data expected in the platform

Then, click Next.

Step 5 : Security

Default administrator password

Enter the password that will be used to access the admin account.

Encryption

Enter the encryption master password, it will be used to generate the encryption key file.
Key storage: you can choose where to store the encryption key file. (avertissement) It should be a secure location. For more information, see Database encryption.

Step 6: Network settings

HTTP port /  Web context root

Here are some examples of  node URLs given an HTTP port and a Web context root.

HTTP port Web context root URL to access the deployment
8080 / http://localhost:8080/
8080 /adi http://localhost:8080/adi/
80 /adi http://localhost/adi/

To use HTTPS instead of HTTP, you must modify some configuration files after the installation is complete. For more information, see HTTP Settings.

Note: If you are installing a node that will belong to a node cluster, each node may have their own specific URL. In a primary-replica cluster, you can configure a primary URL that the end user will use to access dashboards and so on. For more information, see Install a Primary/Replica cluster.

Proxy url

Optional application entry point through HTTP.

Fill this field if you want your users to access the application through a proxy.

Enable JMX

This option enables/disables the JMX feature and the JMX port below.

JMX port

Port that will be used to access the node using JMX protocol.

When you're done with the settings, click Next.

Step 7: Installation

The installation process is shown as a progress bar and can take several minutes.
When the installation has finished (overall installation progress is over), you will be redirected to the last screen of the installer.

Step 8: Installation finished

The software is installed and ready to use.

Check the Create a response file option to relaunch the same installation later without having to go through all the installer screens. The response file is generated in the node installation directory. For more information, see Using the automated mode.

Then, click Done to close the window.

Using the console mode

Launch the installer with this command line:

./DecisionInsight_2.0.0_Install_linux-x86-64_BNXXXXXXXXXX.sh -c

Steps are the same as for the graphical installation mode.

Using the automated mode

You can also install the node in unattended mode from a configuration file.

You should have a previously generated response file that should look like this:

response.varfile
# Destination directory
sys.installationDir=/opt/DecisionInsight
 
# Platform settings
timezone=Europe/Paris
initialVTperiod=2017-08-01
  
# Admin password
hashPassword=4095\:e24f5a84b1b65eddca66a3c4cabdfd22c51bdc2003c2a6e8\:86009c512687a791435ece701cd7de55f167b549bbf090b6
 
# Network settings
httpPort$Long=8080
contextRoot=/myApp
proxyUrl=
jmxEnabled$Boolean=true
jmxPort$Long=1099
 
# Installer settings
sys.adminRights$Boolean=false
sys.languageId=en

# Encryption (only if encryption was not already defined)
encryptionKeyPath=/opt/DecisionInsight/conf
encryptionSaltPath=/opt/DecisionInsight/var/data/titanium-temporal

When upgrading an old node with no encryption support, you cannot do it fully automatically as you first have to generate a key using a tool from an up-to-date node:

  1. Manually generate the key and salt file using the script from an up-to-date node. See How to generate a new encryption.key file?
  2. Manually add the two encryptionKeyPath and encryptionSaltPath to the response file to match the directories where you just generated the files.


Launch the installer from the terminal using the following command:

./DecisionInsight_2.0.0_Install_linux-x86-64_BNXXXXXXXXXX.sh -q -varfile response.varfile

Install the license

A valid license is required to start the node. The license is a file having a .jar or .licence extension.

Copy the license file to the <install dir>/lib/licences directory.

Adjust your persistence parameter

It is recommended to check the settings of the embedded database for better performances.

Update the field com.systar.titanium.initialPeriodValidTimeEnd in <install dir>/conf/platform.properties (Value is a date).

conf/platform.properties
com.systar.titanium.initialPeriodValidTimeEnd=2014-01-01T00:00:00.000

Example 1: If the node is set up on 2014-04-20 simply input this date.

Example 2: The node is set up on 2014-04-20, but past data up to 2014-09-20 is injected, then set the date to 2014-09-20 for optimal performances.

(avertissement) Once the node has started at least once, (and so has started to save data), you can no longer modify this parameter.

(info) The value for this parameter is also used to define the date before which it will not be possible to create an application.

Example: If the node is set up on 2014-04-20, but you wish to create a dashboard valid from 2014-04-10 then set the date to 2014-04-10.

Change the working directory (optional)

To specify the directory where the node can perform read/write operations and where your data will be stored, you can change the <working directory>.

To specify the <working directory> , perform the following steps:

  1. Copy the content of <node directory>/var to  <working directory>.
  2. Edit the following files:
<installation directory>/conf/path.conf
WORKING_DIR="<working directory>"

Change the logging directory (optional)

To specify the directory where the node will write the logging files, change the <logging directory>.

To specify the <logging directory>, perform the following steps:

  1. Copy the content of <working directory>/log to <logging directory>.
  2. Edit the following file:

    <installation directory>/conf/platform.properties
    com.systar.platform.log.dir=<logging directory>

Install as a service (optional)

Multi platform configuration

If you want more than one instance of Decision Insight installed as a service, edit the property com.systar.platform.name= in <installation dir>/conf/platform.properties.

This value will be used as the service name. (Default name is DecisionInsight)


Execute the provided install script located in <installation directory>/bin/tnd-service-register.sh using the <System administration account> user.

> ./<installation directory>/bin/tnd-service-register.sh
setting service auto run levels using update-rc.d
 Adding system startup for /etc/init.d/DecisionInsight ...
   /etc/rc0.d/K01DecisionInsight -> ../init.d/DecisionInsight
   /etc/rc1.d/K01DecisionInsight -> ../init.d/DecisionInsight
   /etc/rc6.d/K01DecisionInsight -> ../init.d/DecisionInsight
   /etc/rc2.d/S99DecisionInsight -> ../init.d/DecisionInsight
   /etc/rc3.d/S99DecisionInsight -> ../init.d/DecisionInsight
   /etc/rc4.d/S99DecisionInsight -> ../init.d/DecisionInsight
   /etc/rc5.d/S99DecisionInsight -> ../init.d/DecisionInsight

This installs the service script in /etc/init. d/ <node name> and sets its run levels to allow auto-start. This command checks that no other service is already registered under the same name before proceeding.

By default, the node runs with root privileges.

On SUSE 12, you might need to enable the service before the first start.

Enable Decision Insight service
> systemctl enable DecisionInsight.service

Change service user account

If you want to change the user that manages the node, modify the startup script /etc/init.d/<node name> and replace the line:

USER=root

to:

USER=<Decision Insight execution account>

Secure your installation (optional)

In order to restrict what files the node can access or modify, you can apply the following rights:

Directory

Decision Insight administration account rights

Decision Insight execution account rights

<installation directory>/bin/

read / write / execute

read / execute

<installation directory>/conf/

read / write / execute

read / execute

<installation directory>/lib/

read / write / execute

read / execute

<installation directory>/product/

read / write / execute

read / execute

<working directory>

read / write / execute

read / write / execute

<logging directory> read / write / execute read / write / execute

Example

In the following example,

  • the Decision Insight administration account is di-admin
  • the Decision Insight execution account is di-exec
  • <installation directory> is /home/decision-insight/app, owner is  di-admin & group is di-admin
  • <working directory> is  /home/decision-insight/data , owner is di-admin & group is di-admin
  • <logging directory> is /home/decision-insight/logs, owner is di-admin & group is di-admin

In /home/decision-insight/data  & /home/decision-insight/logs, set an acl that permit to  di-exec &  di-admin to write in the folder.

[di-admin@server ~]$ cd /home/decision-insight/data #Move to the <working directory>
[di-admin@server data]$ getfacl . # Check current acl
# file: .
# owner: di-admin
# group: di-admin
user::rwx
group::r-x
other::r-x
[di-admin@server data]$ setfacl -Rdm user:di-exec:rwx . # Add (-m) recursive (-R) acl for the user di-exec and for all elements that will be created in this folder (-d)
[di-admin@server data]$ setfacl -Rdm user:di-admin:rwx . # Add (-m) recursive (-R) acl for the user di-admin and for all elements that will be created in this folder (-d)
[di-admin@server data]$ getfacl . # Check current acl
# file: .
# owner: di-admin
# group: di-admin
user::rwx
user:di-exec:rwx
user:di-admin:rwx
group::r-x
mask::rwx
other::r-x

Be sure to add an acl for both di-exec &  di-admin. The node then creates directories and files owned by di-exec and di-admin must to be able to modify them.

Related Links