You are here
eiPlatform IV - General - Installation Guide (Documentation)
eiPlatform - General Installation Guide
The XCS 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 XCS eiPlatform (here-on "eiPlatform") on a Microsoft Windows operating system using screenshots from Microsoft Windows XP SP3. 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.
This document assumes that the following files have been provided to the user and exist on the target machine’s "Desktop":
Operating System: Microsoft Windows XP / Server 2003 or higher (Vista, 7)
Application Container: Apache Tomcat 6
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.
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.6 (JRE 6)
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
Download / Installation of JRE 6
The Java Runtime Environment 1.6 can be found at: http://java.sun.com/javase/downloads/index.jsp
Figure 1.1 – Java SE Download Webpage
Under the "Java SE Runtime Environment (JRE)" heading, the user should be able to download the most recent JRE version. Select the "Download" button (highlighted below):
Figure 1.2 – Java SE JRE Download link, highlighted
You will next be prompted to select a platform. For Windows systems, this will typically be "Windows" or "Windows x64" (if a 64-bit version of Windows is present). You must also select "I Agree" from the terms and conditions, provided these have been cleared with your respective legal department. After doing this, select "Continue" (highlighted below):
Figure 1.3 – Downloading the JRE
You will next be prompted to select a download method, either using the web installation or a direct (offline) installation. It is recommended to use the offline installer, as this can be copied and shared on the local filesystem. The link for this is highlighted below:
Figure 1.4 – The offline installation download 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 15. You may optionally change the installation path, though this is not covered in this document. Continue by selecting "Install" (highlighted below):
Figure 1.5 – 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.6 – Step 2 of the JRE Installation (automated)
Finally, the installation results will be displayed. You can continue and finish the installation by selecting "Close" (highlighted below):
Figure 1.7 – Step 3 of the JRE Installation
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 "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" (highlighted below):
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" 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" (highlighted below). The below screen has the recommended configuration displayed:
Figure 2.5 – Step 3 of the Tomcat Installation, with recommended configuration shown
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" (highlighted below):
Figure 2.6 – Step 4 of the Tomcat Installation, with default installation path 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," though 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" (highlighted below). Please note, the below screenshot is not an optimal configuration:
Figure 2.7 – Step 5 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" (highlighted below):
Figure 2.8 – Step 6 of the Tomcat Installation, showing the JRE path.
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" (highlighted below):
Figure 2.9 – Step 7 of the Tomcat Installation, showing the installation conclusion
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" (highlighted below):
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 to Tomcat's shared library directory, "lib": "quartz-all-1.6.0.jar", located in the eiPlatform’s "WEB-INF/lib" directory, and "jta.jar", which will be provided to you along with the eip.war file.
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:
These parameters are probably located on lines 18 and 23, 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:
This configuration is shown below:
Figure 4.2 – Text section from web.xml with the modifications highlighted
After making these modifications, save your changes.
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::
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
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:
The below image shows these values altered and highlighted to their correct configuration parameters:
Figure 5.2 – The eipServer.conf file with highlighted changes
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, however, that the log configuration file is formatted in XML. You need only alter one tag:
This is typically found on line 14. You will need to change the contents of this tag’s "value" attribute to "/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.
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 service option for Tomcat 6 highlighted