Installing and configuring a new nJAMS instance

The overall installation process of a new nJAMS Server Instance consists of the following main steps:

  1. Install nJAMS Server

    1. Start the installer either for Windows or Unix/Linux
    2. Walk through the installation wizard and select at least WildFly Application Server including configuration and deployment of nJAMS Server.

  2. Optionally setup additional components from nJAMS Server installer:

    1. Install PostgreSQL database
    2. Install Elasticsearch node
    3. Install JMS Provider Apache ActiveMQ

Installing nJAMS Server in GUI mode

There are two installers available.

For Unix/Linux platforms:

  • njams_server_unix_5.1.x.sh

Note

Do not use user “root” for installation, the installation will fail in context of this user.

For Windows:

  • njams_server_windows-x64_5.1.x.exe

The following exemplarily shows the installation process for Windows.

  1. Start the installer executable njams_server_windows-x64_5.1.x.exe.
  2. Confirm User Account Control (UAC) dialog:
Confirm UAC
  1. Click Next on Welcome message:
Welcome message
  1. Select your destination folder and click on Next. Make sure you have sufficient privileges to access this directory:
Select destination directory
  1. Select the type of installation:
Select installation type
Standard:is the default installation type. Standard will install WildFly Application Server and deploy nJAMS Server afterwards.
Full:this installs all software components that come with nJAMS Server installer.
Custom:user can select, which component to install. Use also ‘Custom’ installation, if you want to isntall your own Elasticsearch Cluster or your own RDBMS.

We proceed with “Full installation”, which will install WildFly application Server, an Elasticsearch Node, and Apache ActiveMQ JMS provider.

  1. Configure nJAMS instance:
Configure nJAMS instance

Specify an nJAMS instance name. An instance is the top entity for an nJAMS installation. Typically you have individual nJAMS instances for each environment (dev, test, prod, etc.). Give an name for the Administrator account and for the Administrator role. Set a password for the Administrator account.

  1. Setup WildFly settings:
Specify WildFly settings

Set heap size for the JVM of WildFly. Please select at least 2 GB RAM, which is sufficient in many scenarios. A good practical value is 4 GB for the most common scenarios. You may need more heap size, depending on load, and data volume. Provide a name for the Admin user. Set a password for the WildFly admin user.

Select one of these ip addresses:

Specify WildFly ip addresses
  • 0.0.0.0 listens on all interfaces
  • Your public IP
  • Your local IP
  1. Setup an Elasticsearch Node:
Setup ES

Provide a name for the Elasticsearch Cluster. Provide a name for the Elasticsearch Node.

Note

If you want to add more Nodes, restart nJAMS Server installer after the installation again and select Custom installation / Elasticsearch.

  • Specify a free API port.
  • Select a free HTTP port.

On tab “Heap Size” you can adapt the heap for Elasticsearch:

Specify heap for ES
  1. Select http port of Cerebro management tool:
Select http port of Cerebro
  1. Setup Apache ActiveMQ:
Setup ActiveMQ
  • Define prefix for ActibeMQ destinations of nJAMS Server message processing.
  • Provide username and password for Administrator account of ActiveMQ.
  • Set ActiveMQ administration port.
  • Provide username, password of ActiveMQ account.
  • Set communication port of ActiveMQ.
  1. Create a shortcut for Start Menu:
Create shortcut

Click on Next to start the installation.

  1. If the installation was successful, you will receive a summary of your target installation.
Summary

Check “Open nJAMS in browser” and you can directly login into your new nJAMS instance:

Open nJAMS instance

You can find the installation log files in the folder <install>/.install4j

In case of the installation fails, the installation’s log file can be found in the system’s temp folder:

  • On Windows: ‘’<userprofile>\AppData\Local\Temp'’
  • On Linux: ‘’/tmp’’

Installing nJAMS Server in Console mode

On Unix/Linux systems you can either run installer in GUI mode or console mode. To run the installer in console mode follow these steps:

  1. Extract the content of the package to a temporary directory
  2. Inside console window navigate to temporary directory
  3. Execute njams_server_unix_5.1.x.sh -c
  4. Respond to the console window prompts step by step.

Note

In case you want to use to your own Elasticsearch cluster and you are using authentication and/or SSL, please select ‘n’, when asked, if you want to connect to an existing Elasticsearch cluster.

Installing nJAMS Server in Unattended mode

The unattended mode of the installer allows to run an nJAMS installation automatically by using pre-defined settings. An unattended installation has to refer to a response var file that includes pre-defined installation settings. It is recommended to use a response var file from an attended installation as a template and adapt the settings in this file accordingly. A response var file is generated obligatory and resides in <installationfolder>/.install4j/.

Run installer in unattended mode as follows:

  1. Extract the content of the package to a temporary directory
  2. Inside console window navigate to temporary directory
  3. Execute njams_server_unix_5.1.x.sh -q -varfile response.varfile

Go to response.varfile for more information about response.varfile.

Verify installation

Please follow the instructions below to ensure nJAMS Server is running properly:

1. Check login:

Use a browser to login into nJAMS.

Note

If login is not possible, ensure that the database is up and running and visit the log file: <njams_home>/wildfly16/standalone/logs/njams.log and check for any error messages.
2. Check Indexer:
 

Login to nJAMS and go to Administration -> Connections -> Indexer and ensure that the Indexer client is running. If not, configure your Elasticsearch cluster connection and start the client.
3. Check Data Provider(s):
 

Go to Administration -> System Control -> Message processing and ensure that the Data Provider is running. If the Data Provider is not running, go to Administration -> Connections -> JMS and verify your JMS settings are configured properly. Check whether there is a receiver registered on the JMS Server destination used by nJAMS: <prefix>.event. At least 1 receiver should be registered on that destination.

Deploying 3rd Party Libraries

nJAMS Server Installer includes 3rd party libraries for the enclosed component Apache ActiveMQ. If you want to use different JMS Provider like TIBCO EMS you have to make sure that the according 3rd party libraries are successfully deployed at nJAMS Server.

Deploy 3rd party libraries:
 

Login to nJAMS Server UI and navigate to ‘’Administration -> System Control -> Deployment``:

You can see the list of uploaded and deployed libraries currently used by nJAMS Server. Initially only nJAMS Server WAR file is listed.

Deploy
  1. Click on UPLOAD
  2. Select library (jar file). The library is added to the list and needs to get deployed now.
  3. RESTART nJAMS Server to get the added libraries loaded.

Custom installation of nJAMS Server

nJAMS Server allows you to use your own Elasticsearch Cluster. You can also use your own database system (RDBMS) instead of the built-in nJAMS database.

Select “Custom Installation”, if you want use your own Elasticsearch Cluster or your own RDBMS.

  1. Start nJAMS Server installer
  2. Select “Custom installation”:
Custom installation
  1. Select “Use External Database”, “Elasticsearch” and click on Next:
Select RDBMS, Elasticsearch
  1. Enter settings for RDBMS.
Enter connections for RDBMS
  1. Enter settings for Elasticsearch Cluster.

Make sure you select the correct version of your prepared Elasticsearch Cluster.

ES Cluster connection

Note

If your Elasticsearch cluster is configured with authentication or SSL, you cannot connect nJAMS Server to that cluster during installation. In that case, deselect the Connect to existing Elasticsearch cluster checkbox and complete installation. Afterwards, open Administration -> Connections -> Indexer in nJAMS Server and configure cluster connection there.

Furthermore, follow the instructions of the installation wizard accordingly.

Uninstalling nJAMS Server

To uninstall nJAMS Server start the uninstaller on the machine where nJAMS Server is installed. The uninstaller resides in the nJAMS Server installation folder.

  1. Start nJAMS Server uninstaller:
  • uninstall on Unix/Linux platforms
  • uninstall.exe on Windows
  1. Confirm that you are sure to uninstall all components of nJAMS Server.
Confirm

Click on Next to remove nJAMS Server and all corresponding components.

  1. Uninstaller removes all components from this machine:
Uninstalling
  1. Confirm completion of uninstallation:
Uninstalltion complete