Installing InterformNG2 on Linux

The following instructions provide a recommended approach for setting up InterformNG2 on Linux. This setup has been tested on Ubuntu v22 and is also compatible with other distributions like Red Hat Linux 8, provided the headless version is not used.

Run as a service with systemd (HTTPS version)

1. Install Java Runtime v17

Install Java Runtime v17 (if not already installed) - not the headless variant.

On Ubuntu, install the Java Runtime using the following command:

sudo apt install openjdk-17-jre

2. Create a dedicated user (optional)

For optimal security, it is recommended, though not required, to create a dedicated user specifically for running InterformNG2.

To create a new user, run the following commands:

sudo useradd -m ifng 
sudo passwd ifng

Enter the password when prompted:

sudo usermod -aG sudo ifng

Switch to the newly created user:

sudo -u ifng -s
cd ~

Alternatively, log in as an existing user.

3. Download and unzip

Use the following command to download the application:

wget http://download.interform400.com/shares/SW/InterFormNG2_Linux.zip

Unzip the File to an Appropriate Folder (in this example, /opt/InterFormNG2_Linux is used):

sudo mkdir /opt/InterFormNG2_Linux
sudo chown ifng /opt/InterFormNG2_Linux/
unzip InterFormNG2_Linux.zip -d /opt/InterFormNG2_Linux

4. Move the keystore

Within the folder, move the keystore to the correct location:

 cd /opt/InterFormNG2_Linux
 mkdir keystore
 mv interformng2.p12 keystore/

5. Create a folder for additional JAR files

If you require a database driver, you can place it in this folder. This folder serves as a replacement for the jre/lib/ext folder in Java 8.

mkdir /opt/InterFormNG2_Linux/libext

6. Set file permissions

Make sure that only the user running the application has read access to the files:

chmod -R 500 /opt/InterFormNG2_Linux/

7. Create the service file

Create a new file named /etc/systemd/system/iformng2.service. If you are using a text editor, make sure to run it with sudo, since this location requires root access.

The content of this file depends on your InterformNG2 version. Select your version below.

Version 4.4.0 and newer

From version 4.4.0 the service needs the environment variable INTERFORMNG2_PRIVATEKEY. It is stored in a separate secrets file, not in the service file itself.

Create a file to hold the secret environment variable:

sudo mkdir /etc/iformng2
sudo install -o root -g root -m 600 /dev/null /etc/iformng2/secrets.env

Edit that file:

sudo nano /etc/iformng2/secrets.env

In the file, add this line. Replace RANDOM_VALUE with at least 20 random alphanumeric characters of your choice. This value is used for the primary keystore password.

INTERFORMNG2_PRIVATEKEY=RANDOM_VALUE

Keep a copy of this value somewhere safe. From version 4.4.0 onwards, the value must not change - if it does, the service will fail to start. See Common Keystore for details.

If you have multiple InterformNG2 servers with a common database, INTERFORMNG2_PRIVATEKEY must be set to the same value on all servers.

Then create the service file with this content:

[Unit]
Description=InterFormNG2
After=syslog.target

[Service]
User=ifng
Environment="INTERFORMNG2_HOME=/home/ifng/NG2Home"
EnvironmentFile=/etc/iformng2/secrets.env
WorkingDirectory=/opt/InterFormNG2_Linux
ExecStart=/bin/java -Xms512M -Xmx4096M \
  -Djava.locale.providers=COMPAT,CLDR \
  -Djava.io.tmpdir=/home/ifng/NG2Home/temp \
  -cp /opt/InterFormNG2_Linux/InterformNG2-x.y.z.jar:libext/* \
  org.springframework.boot.loader.launch.JarLauncher
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

Replace x.y.z with your installed InterformNG2 version.

Version 4.2.0 to 4.3.2

[Unit]
Description=InterFormNG2
After=syslog.target

[Service]
User=ifng
Environment="INTERFORMNG2_HOME=/home/ifng/NG2Home"
WorkingDirectory=/opt/InterFormNG2_Linux
ExecStart=/bin/java -Xms512M -Xmx4096M \
  -Djava.locale.providers=COMPAT,CLDR \
  -Djava.io.tmpdir=/home/ifng/NG2Home/temp \
  -cp /opt/InterFormNG2_Linux/InterformNG2-x.y.z.jar:libext/* \
  org.springframework.boot.loader.launch.JarLauncher
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

Replace x.y.z with your installed InterformNG2 version.

In these versions, no privateKey is required.

Before version 4.2.0

Use the same service file as for versions 4.2.0 to 4.3.2 above.

In addition, these versions require a privateKey. Edit the file /opt/InterFormNG2_Linux/application-default.properties and add this line:

interformng2.privateKey=<RANDOM-STRING>

Where <RANDOM-STRING> is indicated, enter your own randomly generated string with a minimum of 32 characters. This string is used as an encryption key, so it is important to choose a long, unique value for each installation.

Note: you can set this value as an environment variable instead of in application-default.properties. However, using a dot (.) in the variable name may lead to potential issues.

8. Enable and start the service

Finally, set it to start up automatically after a system restart, and then start the service:

sudo systemctl enable iformng2
sudo service iformng2 start

In case of startup problems, view the console log:

sudo journalctl --unit=iformng2

9. Additional consideration

It is important to consider which users need access to the INTERFORMNG2_HOME directory, and set file permissions accordingly to ensure optimal security.

In the example provided, the ifng user's home directory is used for the InterformNG home folder (/home/ifng/NG2Home). However, this may not be ideal if other users need access to the folder via the file system.

In the example, the maximum memory allocation for InterformNG2 is set to 4GB using -Xmx4096M. This value can be adjusted as required.

The startup parameters include -Djava.locale.providers=COMPAT,CLDR. This setting ensures that date format strings generated by InterformNG2, such as those from the ng:dateTimeFormat() XPath function, remain consistent with the format used in previous Java 8 versions. While this setting is recommended, it is optional.

The temporary work files directory is set with -Djava.io.tmpdir in the service file above. You can change this to another directory if required.

10. Upgrading an existing installation

To upgrade the Linux installation to a newer version of InterformNG2, without touching any configuration changes made to application-default.properties or keystores, follow this procedure. This assumes that the recommended installation procedure was previously followed.

Download the latest version of InterformNG2:

wget http://download.interform400.com/shares/SW/InterFormNG2_Linux.zip

Unzip to a temporary folder:

unzip InterFormNG2_Linux.zip -d temp/

Stop the running service:

sudo service iformng2 stop

Make the installation folder writable:

chmod -R 700 /opt/InterFormNG2_Linux/

Delete old files (only these files, do not remove other files in the folder):

rm /opt/InterFormNG2_Linux/InterformNG2-x.y.z.jar

(replace x.y.z with the OLD InterformNG2 version)

rm -r /opt/InterFormNG2_Linux/modules

Copy the new files from the temporary folder:

cp temp/InterformNG2-X.Y.Z.jar /opt/InterFormNG2_Linux/

(replace X.Y.Z with the NEW InterformNG2 version)

cp -r temp/modules /opt/InterFormNG2_Linux/

Make the files read-only again:

chmod -R 500 /opt/InterFormNG2_Linux/

Edit the existing /etc/systemd/system/iformng2.service (with sudo) and change the version number on InterformNG2-x.y.z.jar to the new version number.

Start the service again:

sudo systemctl daemon-reload
sudo service iformng2 start

11. Upgrading to version 4.4.0

In addition to the steps above, version 4.4.0 requires the environment variable INTERFORMNG2_PRIVATEKEY. Create the secrets file as described under Version 4.4.0 and newer in step 7, then add this line to the [Service] section of /etc/systemd/system/iformng2.service:

EnvironmentFile=/etc/iformng2/secrets.env

The ExecStart line does not need to be changed. After editing the service file, run sudo systemctl daemon-reload before starting the service.

If you already have a privateKey value defined, you can either continue using the existing value or create a new one - it makes no difference.

From version 4.4.0 onwards, the value must stay the same. If it changes, the service will fail to start. Keep a copy of the value stored somewhere safe as a backup.

Setup of temporary work files on the Linux platform

On the Linux setup above you can change the recommended iformng2.service description above to include temp directory with the highlighted/bold text below:

ExecStart=/bin/java -Xms256M -Xmx4096M \
  -Djava.io.tmpdir=/home/ifng/NG2Home/temp \
  -jar /opt/InterFormNG2_Linux/InterformNG2-1.5.1.jar