eiDashboard v.20R1

eiDashboard – Linux Installation

This page will take you through the installation process of the 20R1 eiDashboard for Linux and is based on Amazon Linux 2.

The only prerequisite for this installation is to have a PostgreSQL or MS SQL Server database instance installed and for the eiDashboard instance to have JDBC access to the database with permission to read and write.

It is also recommended that eiDashboard General Configuration documentation be read before installing the eiDashboard. It will help to understand what you are setting up and how the eiDashboard interacts and monitors eiPlatform’s.

Installation of Java 11 and Tomcat

On Linux, WAR files are used in conjunction with Tomcat to deploy PilotFish server applications.  Currently, PilotFish needs Java 11 to operate so that will be the version of Java used for both Tomcat and PilotFish.

Please follow these steps for information on how to setup Java and Tomcat on Amazon Linux 2.

Installation of WAR Files

The eiDashboard and back-end eiPlatform must be of the same major version release (20R1 eiDashboard and 20R1 eiPlatform) to guarantee compatibility with the eiDashboard back-end Routes.  eiPlatform instances monitored by an eiDashboard should be at least version 17R2.

To start, you can simply drop your WAR files into the tomcat/webapps directory.  If Tomcat is running it will automatically explode out the files into the directory.  It is recommended that the eiDashboard WAR file be named dashboard.war and eiPlatform WAR file be named eip.war.  Ultimately the names of these files will be the name of the resource path that allows you to interact with the web application.  Example being, to connect to the eiDashboard in this scenario, with default port for Tomcat being 8080, the address in the browser would be http://127.0.0.1:8080/dashboard, and for the eiPlatform http://127.0.0.1:8080/eip

Setting Up the Back-End eiPlatform

At this point, the eiPlatform will need to be configured to connect to a database. In this tutorial, we are following our reference implementation (PostgreSQL) of the eiDashboard.  Provided alongside the eiDashboard WAR file is a separate ZIP file containing the back-end routes and schema to be used with the back-end eiPlatform.  The schema, once loaded into your database will seed all necessary information to log into the eiDashboard as well as for Transaction Logging.

If you have not already, you should create a database as well as a user with read and write access to the said database as the next steps assume that this is setup.  You can find documentation on how to do this at PostgreSQL’s site.

You can find the schema inside the zipped Working Directory.  Unzip the working directory and navigate to the working directory root “data” folder and you will find Postgresql_txnlogging_schema.sql.  This file is the only SQL you will need to run if you are doing a fresh install.

Next, you will need to configure the routes.  This can be done by moving the contents of the unzipped working directory into the eip-root of the exploded eip.war tomcat directory:

After doing so the contents of the eip-root folder should look like the following:

Double-check the lib folder has the postgresql-42.2.8.jar and that the Interfaces folder has all 4 interfaces: Dashboard, Maintenance, PersistTransactions and Tests.

Once that is done you can move on to modifying the environment-settings.conf that is found under eip-root.  The default will look similar to this:

To briefly explain each entry similar to the following: {ognl\:\#system.getenv(‘PFISH_DASH_CONF_com_pilotfish_eip_txlog_dbDriver’, ‘org.postgresql.Driver’)}

The environment properties may look a little strange, but this is because we are using OGNL to set the value of the property. The OGNL for each property does the same thing except the values change for each. Essentially what it is doing is checking if there is a Tomcat Environment variable of the name PFISH_DASH_CONF_com_pilotfish_eip_txlog_dbDriver, and if so, uses that value over the org.postgresql.Driver value. This means you can set your database credentials at the Tomcat level rather than directly in the configuration file. Either method is fine and can be set to your discretion.

Postgresql_Driver is the full classpath to the driver installed in your embedded EIP’s eip-root/lib folder. Likely you can leave this as a default

Postgresql_Password is the password to the user created in your database

Postgresql_URL is the JDBC url to your database.  Connecting to a locally running PostgreSQL database with database named txlogdb would have a JDBC url of jdbc:postgresql://localhost:5432/txlogdb

Postgresql_Username is the username of the user created in your database

So if the username is ‘test’ and password was ‘test’ with the URL mentioned above, the settings would look like this:

Postgresql_Driver={ognl\:\#system.getenv(‘PFISH_DASH_CONF_com_pilotfish_eip_txlog_dbDriver’, ‘org.postgresql.Driver’)}
Postgresql_Password={ognl\:\#system.getenv(‘PFISH_DASH_CONF_com_pilotfish_eip_txlog_dbPass’, ‘test’)}
Postgresql_URL={ognl\:\#system.getenv(‘PFISH_DASH_CONF_com_pilotfish_eip_txlog_dbUrl’, ‘jdbc:postgresql://localhost:5432/txlogdb’)}
Postgresql_Username={ognl\:\#system.getenv(‘PFISH_DASH_CONF_com_pilotfish_eip_txlog_dbUser’, ‘test’)}

At this point you will also need to install your pflicense.key license file into the exploded eip.war directory (…/webapps/eip).

If you do not have or cannot find this file, please contact us.

Finally, you will need to tell the eiDashboard how to connect into the back-end routes.  Navigate to the exploded dashboard.war directory under the Tomcat webapps directory.  Beneath that, you will find a WEB-INF folder.  In that folder will be a configuration file called dashboard.conf, as seen below:

Open dashboard.conf

The setting to look for is com.pilotfish.dashboard.txlogapi.url. This will need to point to the eiPlatform’s RESTful listeners running the back-end routes.  The default http://localhost:8080/eip/rest should work for default Tomcat settings, but if running at a different port IP, this will need to be modified.

At this point, everything should bet set up and you can move on to setting up the remaining bits from the eiDashboard GUI in your web browser.

First Login and Instance Setup

You will need to restart the Tomcat service at this point to apply all the changes made

Once the service is started, it can be accessed through a web browser.  The default port for Tomcat is 8080, so if you are testing it out on the same machine that is running the dashboard the URL would be http://localhost:8080/dashboard.

Note: The below screenshots show port 8989.

When the page loads in, you can log in using the default credentials, user: admin password: admin.  For security reasons, we will modify these in a later step.

Once you are logged in you should see the EIP instances page below.  As an administrator, you will have access to the Administration tab at the top right.

After clicking on the tab you will be presented with the following administration page.

The administration page allows you to add eiPlatform instances for monitoring as well as manage users and their access to eiPlatform instances.  eiPlatform instances are uniquely identified in the database based on their EIP Id.  This is the system name by default but can be manually set in the monitored eiPlatform’s eipServer.conf settings.  This will be necessary if you are running more than one EIP instance on a single system.  Please see the eipServer.conf settings information for more details.

Change your administrator password

To change the password, click the yellow ‘Edit Password’ button in the Users section for the admin user.

If you click Add Instance, you will be presented with the following window:

You will need to enter in the monitored eiPlatform’s EIP Id as well as the location of the eiPlatform.  The URL is usually the IP address at port 8443 on Windows installs, or on Tomcat it will be port 8080.  Example URLs are as follows:

http://127.0.0.1:8443     (Windows Install)

http://127.0.0.1:8080/eip (Tomcat Install)

Once added you should be able to see your eiPlatform in the Instances tab as seen below:

When logging into an eiPlatform, it should be noted that there is yet another layer of users and permissions specific to the individual eiPlatform instances.  These can be managed through the eiDashboard once logged in, but you will have to set up the RESTful API super user for the initial configuration.  For information on how to set up the initial user see Using the eiPlatform REST API.

Once that is set up you can simply login by clicking on the instance name in the table.  You will be presented with a login popup that requires credentials set to the individual EIP instance.

Once entered correctly you will be logged into the Dashboard page for your monitored EIP!