Installation and Configuration
Recommended Installation Environment
- eiDashboard version 1.1
- eiPlatform & eiConsole Windows installation bundle at least version 13.17R2 (Q2 2017 release) or eiPlatform WAR installer
- Apache Tomcat version 7.0+ or 8.0+ (for Tomcat installations only)
- Microsoft Windows 10 (for Windows Service installations only)
Installation instructions will vary, depending mainly on the preferred mode of operation and application deployment. If only Basic Statistics Mode is needed (simple transaction throughput statistics), then configuration will be minimal. Full multi-eiPlatform Enterprise mode with Transaction Logging will require more in-depth configuration.
Every eiDashboard installation will follow the same basic steps:
- Install/upgrade the eiPlatform and eiConsole (not covered in this guide)
- Install the eiDashboard core
- Configure eiPlatform and eiDashboard settings
- Configure users and access permissions (covered in detail here)
Installing the eiDashboard Core
This guide will cover both Windows Service and Tomcat application container installation processes. The method of installation will depend largely on the deployment environment, though the installed product will be the same no matter the installation.
Microsoft Windows Service installation
Using the Microsoft Windows installer provides a more guided experience than installing into Tomcat and is the recommended method of installation if Windows is your primary operating system.
The installation process is generally self-explanatory, though we will highlight two pages in more detail.
eiDashboard Service Name
On this page, you have the option of selecting the name that Windows will use for your eiDashboard Service. It can be named whatever you’d like, though choosing an intuitive name or keeping the default is recommended since it is difficult to change later.
eiDashboard Windows Service Configuration
Since the eiDashboard and eiPlatform communicate through an internal RESTful API, it is important they are able to communicate properly over your network. These values can vary greatly depending on your network topography, but they are easy to change later – so feel free to leave the default values if you are unsure during installation. The eiDashboard Port setting is the port you would like the eiDashboard to be available from. Be sure to choose a port that is available to avoid conflicts with other programs. The default is port 8989.
The eiDashboard EIP URL setting is the URL where your eiPlatform’s internal API is located.
Starting and Stopping the eiDashboard Windows Service
Starting and stopping the Windows Service can be done through the ‘Services’ menu, available through the Windows system settings. The screenshot below shows both the eiDashboard and eiPlatform services, though the names of each will vary if changed during installation.
Steps for deploying to the Tomcat webapps/directory:
Installing to Tomcat is as simple as copying the .war files for your eiPlatform and eiDashboard into the webapps directory for your Tomcat installation. When Tomcat starts, it will automatically build the applications and start the necessary web services and then configuration can continue as needed.
Note: When installing to Tomcat, the port of your eiDashboard will be the same as your Tomcat port (default 8080). Unlike the Windows installation, the connection to your eiPlatform must be configured manually when using Tomcat. This process is detailed in the next section.
eiPlatform and eiDashboard Configuration Settings
After installing the core eiDashboard product, we must configure several items to ensure it is able to communicate properly with your eiPlatform instances. Some of these configuration values will vary depending on your specific architecture setup, but the settings and their locations are standard across installations.
eiPlatform Configuration Settings
There are only three settings we’ll need to add to the eiPlatform’s eipServer.conf file to enable basic operation of the eiDashboard, although there are a few more settings needed to enable additional functionalities.
First, we’ll need to create credentials for the eiPlatform Super User. These two settings are:
- com.pilotfish.eip.dashboard.User = <Admin Username>
- com.pilotfish.eip.dashboard.Password = <Admin Password>
This user will be able to log into the eiDashboard no matter the other user settings defined in the eiDashboard itself and will have unrestricted access to content, user creation and security settings. It is intended for use by the administrator of your PilotFish architecture to create new users and access capabilities.
Note: For a fresh installation of the eiPlatform, these settings may already be defined but left without values. It is important to create these Super User credentials since, without them, the eiDashboard’s login functionality will be limited.
The screenshot below shows an example of an eipServer.conf file with the pertinent eiDashboard settings highlighted. Your particular configuration file’s contents may vary.
eiDashboard Configuration Settings
The majority of the configuration required in the eiDashboard itself involves configuring the connections.xml file found in the WEB-INF directory of the eiDashboard installation. This xml file contains the information needed to connect the eiDashboard with an eiPlatform instance. Generally, you will only be concerned with two elements:
- The <txnLogAPIPath> element. This setting is most important when using Transaction Logging Mode and points to the URL path of the eiPlatform where the transaction logging interfaces are running. If you are only using Basic Statistics Mode, this setting should be left blank.
- The <Connections> elements. There may be multiple <Connection> elements depending on the complexity of your PilotFish architecture, but each one represents an eiPlatform instance connection. The <url> element of each should point to the eiPlatform’s API root, generally found at http://<URL Path>:8080/eip/ for Tomcat installations or http://<URL Path>:8443/eip/ for Windows installations.
Logging In and eiDashboard Settings
After the internal configuration, the eiDashboard is operational in Basic Statistics mode and ready to go! The next steps are to login for the first time, check and edit the global eiDashboard settings if desired and configure the user and access capabilities.
Loading and Logging In
Since the eiDashboard is an entirely web-based application, it can be accessed from any web browser or mobile device with internet capabilities. The URL will vary depending on the port settings provided during setup. But for a typical Tomcat installation, it can be found at ‘http://localhost:8080/dashboard-ui-1.1/index.html’, while the default Windows URL is ‘http://localhost:8989/dashboard/index.html’. The screenshot below shows the initial eiDashboard login screen.
Selecting the ‘Settings’ button shows all configured eiPlatform connections. Choosing a new connection is as simple as selecting it from the ‘Platforms’ box and hitting ‘Apply’.
Since no eiDashboard users currently exist in our fresh installation, we’ll login with the Super User credentials configured in the previous steps. (For this example ‘eip’ / ‘eip’). If our connections are setup properly, we should be redirected to the eiDashboard Front Page. If there are any errors logging in, a bad password or connection setting (for example), notifications will display on the right side of the screen describing the error. The screenshot below shows the eiDashboard Front Page.
Each piece of functionality is described in more detail in the CMS page for that feature, so for now we will only concern ourselves with the ‘Settings’ page.
Next, we’ll check the eiDashboard internal settings. These are separate for each user and handle visual settings within the eiDashboard like color scheme, toolbar placement, etc. To get to the Settings menu, click on your username in the top-right and then select the ‘Settings’ option in the drop-down that appears.
The Global Settings menu is shown below. Each setting is fairly self-explanatory and deals primarily with visual aspects of the eiDashboard. Any changes are immediate, so once you are done the ‘Close’ button will take you back to the Front Page.
At this point, the eiDashboard is fully operational in Basic Statistics mode, also called ‘Bare-bones mode’. This mode allows for the eiDashboard to connect to one eiPlatform at a time and users can login using either the Super User credentials defined in the eiPlatform settings or any user credentials that have been defined within the eiDashboard itself.
In Basic Statistics mode, basic transaction statistics are available – including throughput and transaction success or error metrics. To extend the eiDashboard’s functionality through the Transaction Logging and/or Enterprise Modes, additional configuration is required. For additional information on each of the extended modes and installation instructions, see the following links:
Generally, the next step in the installation process is to configure users and access permissions. An in-depth guide to the eiDashboard’s user administration system can be found here.
The following section covers some common installation and configuration issues you may have, typically when first attempting to log into the eiDashboard. Due to the complexity of many network systems, establishing a proper connection between the eiPlatform API and the eiDashboard can sometimes take some tweaking.
Failed to Authenticate User
Typically authentication issues occur when the Super User configuration items are not set in the eiPlatform’s eipServer.conf file. As a fail-safe, these credentials have to be defined to enable eiDashboard login functionality, though they can be as complicated as you like for the sake of security.
Authentication errors can also happen if a user or capability is missing some access rules. For example, if the API Access rules are not set when creating a new capability, any users using that capability will have login issues.
Connections issues also can occur when first configuring the eiDashboard. Double-checking your host and port settings is the easiest way to ensure these issues don’t happen. All Tomcat deployed applications default to port 8080, so the connection URL will be ‘http://localhost:8080/eip/’ for the eiPlatform. On a Windows Service installation, the eiPlatform can be reached at simply ‘http://localhost:8443/’ by default. It can take some trial and error to get your eiPlatform and eiDashboard communicating properly but once the connection settings are setup correctly, there shouldn’t be a need to change them.
Additionally, when connecting the eiDashboard to an eiConsole running in Platform Emulator mode, the connection URL will be ‘http://localhost:9001/eip/’ and the txLogAPIPath will be ‘http://localhost:9001/eip/rest/’.
Transaction Log API Issues
When upgrading from the eiDashboard 1.0 to the newest version 1.1, you may encounter some errors after logging in regarding the Transaction Log API, similar to the one shown below:
These errors are caused by eiDashboard-related eipServer.conf settings that have changed or been re-purposed since version 1.0 and can be fixed by removing the following settings (if they exist) in your eipServer.conf:
These settings are only needed for Transaction Logging Mode and when using Basic Statistics Mode they can cause conflicts if set incorrectly.