eiPlatform

eiConsole v.19R1
Documentation

eiPlatform – Installation Guide

The eiPlatform is typically distributed as a WAR file – a compressed archival file which is deployable to most standard J2EE-compliant application containers. It requires a minimal amount of steps to get running inside an application container and uses configuration files outside of the WAR file or its extracted directory structure.

This guide will cover installing the eiPlatform (hereinafter “eiPlatform”) on a Microsoft Windows operating system using screenshots from Microsoft Windows 8.1. The installation steps should not vary greatly between Windows variants. This guide will also cover installing Apache’s Tomcat 6 application container/server as a Windows service.

Prerequisites

This document assumes that the following files have been provided to the user and exist on the target machine’s “Desktop”:
eip.war
eipServer.conf
logConfig.xml

Software Requirements

Operating System: Microsoft Windows XP / Server 2003 or higher (Vista, 7, 8, 8.1, 10)
Application Container: Apache Tomcat 6

Technical Requirements

Any machine capable of running the required software (operating system and application container) should be able to run the eiPlatform, which has extremely low technical requirements. Please note that the eiPlatform does benefit from increased computational power and available memory.
At least one gigabyte (1 Gb) of free hard-drive space is recommended.

Procedural Overview

The installation of the eiPlatform occurs over several main stages, around which this document is organized. The correct installation of Microsoft Windows is assumed. The stages of installation are as follows:

1. Download and installation of Java Runtime Environment 1.8 (JRE 8)
2. Download and installation of Apache Tomcat 6
3. Deployment of the eiPlatform WAR into Tomcat
4. Modification of deployed eiPlatform’s “web.xml” file to point to configuration files.
5. Creation of the eiPlatform’s directory structure
6. File-based configuration of the eiPlatform
7. Starting and stopping the Tomcat service

I – Download/Installation of JRE 8

The Java Runtime Environment 1.8 can be found at: http://www.oracle.com/technetwork/java/javase/downloads/index.html

Under the “Java SE Runtime Environment (JRE)” heading, the user should be able to download the most recent JRE version. Select the “JRE Download” button (highlighted below).

Figure 1.1 – Java SE Download Webpage

You will next be prompted to choose an appropriate version of software for your current system. You must also select “Accept License Agreement” from the terms and conditions, provided these have been cleared with your respective legal department. After doing this, click on desired link. In our case, the JRE version for Windows x64 (highlighted below).

Figure 1.2 – Java SE JRE Download link, highlighted

You will next be prompted to download the application for a direct (offline) installation.

Once the executable finishes downloading, it should be run/executed – either by double-clicking it in a file browser context or selecting it and hitting the Return/Enter key. The first step of the installation should look something Figure 1.3. You may optionally change the installation path, though this is not covered in this document. Continue by selecting “Install” (highlighted below).

Figure 1.3 – Step 1 of the JRE Installation

The next step is largely automated and will require no user invention. It typically looks something like the image below.

Figure 1.4 – Step 2 of the JRE Installation (automated)

Finally, the installation results will be displayed. You can continue and finish the installation by selecting “Close”.

Figure 1.5 – Step 3 of the JRE Installation

II – Download/Installation of Apache Tomcat 6

Apache Tomcat 6 can be found at: http://tomcat.apache.org/download-60.cgi

Figure 2.1 – Apache Tomcat 6 Webpage

Under Binary Distributions, there should be a header entitled “Core.” The “32-bit/64-bit Windows Service Installer” should be selected from this group, which should automatically begin the download of the Apache Tomcat 6 installation executable.

Figure 2.2 – The installer link, highlighted

Once the executable finishes downloading, it should be run/executed – either by double-clicking it in a file browser context or selecting it and hitting the Return/Enter key. The first step of the installation should look something Figure 2.3. Continue by selecting “Next” (highlighted below).

Figure 2.3 – Step 1 of the Tomcat Installation

The next step of the installation is the review of the licensing agreement. Please read through the license in its entirety or, if already cleared by your respective legal department, continue. Select “I Agree”.

Figure 2.4 – Step 2 of the Tomcat Installation

The next step of the installation dictates the installation parameters, allowing the user to determine which components to install. The “Tomcat/Service Startup” and “Tomcat/Native” parameters are recommended, as well as the “Start Menu Items.” The “Documentation” and “Examples” are not necessary nor are they recommended. After configuring the installation, select “Next”.

The below screen shows the recommended configuration displayed.

Figure 2.5 – Step 3 of the Tomcat Installation (with recommended configuration shown)

The next step of the installation determines some basic parameters for the Tomcat service – including its main listening port, administrator username and administrator password. It is recommended to leave the port at the default “8080” – please note that this may be a security concern, as the port is well-known for running Tomcat. Additionally, the administrator username should be modified as well as the password. Tomcat is installed, by default, with the ability to “hot”-deploy applications from the web front-end. Depending on the network exposure of the system in question, it is possible for users outside the system to use this front-end to deploy volatile software to the application container. Make sure to select a username and password consistent with your internal security policies. Once you have completed this, select “Next”.

Please note – the below screenshot is not an optimal configuration.

Figure 2.6 – Step 4 of the Tomcat Installation (do not use the provided settings)

The next step of the installation dictates the location of the Java Runtime Environment (JRE) installed in the first stage. The Tomcat installer will usually find the correct path by default. If not, please manually specify the path used in the first stage. After specifying or accepting the (default) path, select “Install”.

Figure 2.7 – Step 5 of the Tomcat Installation (showing the JRE path)

The next step of the installation determines the installation path. The default provided by the installer is recommended. After (optionally) modifying the install path, select “Next”.

Figure 2.8 – Step 6 of the Tomcat Installation (with default installation path shown)

Tomcat should now successfully install. If you run into any issues during the installation, please consult a system administrator – PilotFish Technology or the Apache Software Foundation. The next and final screen is the conclusion of the installation, where you may opt to start the Tomcat service (recommended). When you are done, select “Finish”.

Figure 2.9 – Step 7 of the Tomcat Installation (showing the installation conclusion)

III – eiPlatform WAR Deployment

To install and deploy the eiPlatform to the Tomcat application container, you must first have the “eip.war” file available to you. This can be obtained from PilotFish Technology directly or via a system administrator with prior access to it. This section of the document assume the file has been provided and copied to the target system’s “Desktop.” This section does not document obtaining the file – either by download or copying from any source.
The first step of the deployment is to open Windows Explorer. This can be done from selecting that item from the Start Menu or using the run context and entering the program name directly. This document assumes the latter. Hold the Windows key and press “R” on your keyboard. This should open the following dialog:

Figure 3.1 – The Run dialog

Next, you’ll need to specify the program name. Windows Explorer is under the main Windows path as “explorer” – type this (without quotes) into the dialog and select “OK“.

Figure 3.2 – The run dialog (with explorer specified)

Windows Explorer should now open. Navigate to the Desktop and copy the eip.war there.

Figure 3.3 – Copying the eip.war file

You will next need to navigate to the Tomcat installation directory and select the “webapps” subdirectory. The eip.war file should be copied into that directory.

Figure 3.4 – Placing the eip.war copy into the Tomcat webapps directory

You have two options at this point – you can start up the Tomcat service or you can extract the eip.war directly. If Tomcat is already running or is started, it will extract the eip.war file to an eip directory. This section assumes manual extraction. Using a compression tool such as 7-zip or Winzip, extract the eip.war file to an “eip” directory. The structure should look something like this:

Figure 3.5 – The extracted eip.war in the directory structure

You may be required to copy two libraries from the eiPlatform’s “WEB-INF/lib” directory – “quartz-all-1.6.0.jar” and “j2ee-1.3.1.jar” to Tomcat’s shared library directory, “lib.”

IV – Web.xml Configuration

You will now need to configure the “web.xml” file located in the extracted eiPlatform directory structure. This file can be found under “webapps/eip/WEB-INF” and is shown highlighted below:

Figure 4.1 – Web.xml in the directory structure

This file can be edited with any text editor, though it is formatted according to UTF-8/Unicode conventions and therefore does not use carriage returns in addition to endlines. It is recommended to use Wordpad, Textpad or a similar sufficiently advanced text editor. This configuration file is written in XML and contains two entries which need to be modified:
web-app/init-param[2]/param-value
web-app/init-param[3]/param-value

These parameters are probably located on lines 33 and 37, respectively. The first refers to the log file location and the second to the eiPlatform configuration file. Alter these tags to have these respective values:
c:/opt/PilotFish/logs/eip.log
c:/opt/PilotFish/conf/eipServer.conf

This configuration is shown below:

Figure 4.2 – Text section from web.xml with the modifications highlighted

After making these modifications, save your changes.

V – Creating the eiPlatform Directory Structure

You will now need to create the eiPlatform’s directory structure, which will contain a folder for configuration, for logs and the eiPlatform’s working directory. The web.xml file modified earlier expects this structure to fall under “/opt/PilotFish,” where the root level denotes the main hard-drive. Typically this is “C:” on Windows systems and this document assumes this is the case for your installation.
You should create the following structure under C::

C:/opt
C:/opt/PilotFish
C:/opt/PilotFish/conf
C:/opt/PilotFish/logs
C:/opt/PilotFish/tmp
C:/opt/PilotFish/eip-root

You should now copy the provided “eipServer.conf” and “logConfig.xml” files from the Desktop into “C:/opt/PilotFish/conf.” The below image shows the completed directory structure with both configuration files present.

Figure 5.1 – The eiPlatform directory structure, with configuration files

Since the C:/opt/PilotFish/eip-root is the working directory a typical structure should be created for it:

C:/opt/PilotFish/eip-root/data
C:/opt/PilotFish/eip-root/formats
C:/opt/PilotFish/eip-root/lib
C:/opt/PilotFish/eip-root/routes

VI – File-Based eiPlatform Configuration

The first file to be configured is “eipServer.conf,” which is the main eiPlatform configuration file. It is shown highlighted in the image below:

Figure 5.1 – The eipServer.conf file in the directory structure

This file is plain text and can be opened with any standard text editor. Wordpad, Textpad or any sufficiently advanced text editor is recommended. The eiPlatform configuration file is a key/value set of properties of the form “key=value.” Endlines designate the end of a property or key definition.

There are three configuration items that will be addressed in this section:
1. The eiPlatform backend database connection, which will be disabled
2. The working directory location
3. The log configuration file location

The items are specified by the keys “com.pilotfish.eip.database.plugin,” “com.pilotfish.eip.configDirectory,” and “com.pilotfish.eip.logConfigFile,” respectively.

You should set these values like so:
com.pilotfish.eip.database.plugin=pilotfish:Null
com.pilotfish.eip.configDirectory=c:/opt/PilotFish/eip-root
com.pilotfish.eip.logConfigFile=c:/opt/PilotFish/conf/logConfig.xml

The below image shows these values altered and highlighted to their correct configuration parameters:

Figure 5.2 – The eipServer.conf file with highlighted changes

If eiPlatform API access is desired, for example, to enable hot deployment functionality or remote eiPlatform access, you must also set configuration items for API login credentials, like so:

com.pilotfish.eip.dashboard.User=<Desired Username>
com.pilotfish.eip.dashboard.Password=<Desired Password>

It is important to note that anyone with these credentials will have fully functional access to the eiPlatform’s API, so make sure they are secure and difficult to guess.

Save the changes to the file. You will next need to alter “logConfig.xml,” shown highlighted in the directory structure below.

Figure 5.3 – The logConfig.xml file in the directory structure

This file can be opened and edited in the same manner as the “eipServer.conf” file.

Note –  that the log configuration file is formatted in XML. You need only alter one tag:
/log4j:configuration/appender/param[1]

This is typically found on line 14. You will need to change the contents of this tag’s “value” attribute to “c:/opt/PilotFish/logs/eip.log.” This change is shown below:

Figure 5.4 – The logConfig.xml file with highlighted changes

Save the changes to the file and close it.

VII – Starting/Stopping the Tomcat Service

There are two ways to work with the Tomcat service. By default, the installation typically provides an icon in the Start Menu notification area which can be right-clicked to raise a context menu. That menu contains items to start and stop the Tomcat service, as shown below:

Figure 7.1 – The Tomcat context item

If this item is not available, you can use the Windows Services tool to start and stop the service. This can be accessed via the Windows “run” prompt by specifying “services.msc.” This can be done from selecting that item from the Start Menu or using the run context and entering the program name directly. This document assumes the latter. Hold the Windows key and press R on your keyboard. This should open the following dialog:

Figure 7.2 – The Run dialog

Next, you will need to enter “services.msc,” and press “OK,” as shown below:

Figure 7.3 – Specifying and running “services.msc”

This should raise the Services dialog, which looks something like this:

Figure 7.4 – The Services dialog

From this dialog, select “Apache Tomcat 6.” The left-hand panel will then give you the option to either Start or Stop the service, depending on its current state, as shown below:

Figure 7.5 – The Start/Stop/Restart service option for Tomcat 6