MPI Installation Manual

System requirements

Disk and memory requirements are depending on the number of transactions that are processed per given time unit and on the number of configured entities (Schemes, Acquirers and Merchants).

Disk requirements

The MPI writes an application-, a message- and a statistics-log (see Log4j Configuration). Every transaction generates around 10-15 kB of log output (with the default log settings). Use this number to calculate the disk space required and to setup a job for archiving log files.

Example: If the MPI processes around 1000 3-D Secure transactions per hour, the MPI writes around 240-360 MB of log output per day.

Memory requirements

Every MPI node consumes around 1.5 GB of memory (embedded Tomcat and application).

Add around 20 kB per configured entity (Scheme, Acquirer or Merchant).

Example: A configuration with 4 Schemes, 100 Acquirers and 10000 Merchants consumes around 202 MB of additional memory.

While a 3-D Secure transaction is ongoing, it consumes session memory. Every session needs around 2 kB of memory.

Example: Assume the MPI processes around 1000 3-D Secure transactions per hour. Every transaction takes around 5 minutes. In average we have around 83 ongoing transactions at any given time (assuming transactions are evenly distributed). Those ongoing transactions consume around 166 kB of session memory.

Operating system

The MPI is recommended to be run on a Linux/Unix based operating system. E.g.

  • a GNU/Linux distribution (Example: CentOS)
  • a BSD derivative (Example: OpenBSD)
  • Mac OS X
  • Solaris

It's possible to run the MPI on Windows. However, you will have to write your own scripts to control (i.e. start/stop) MPI instances. Alternatively you can install Bash and additional tools (rm, dirname, tail, less) on Windows (e.g. via Cygwin) to run the mpictl script shipped with the MPI.

Prerequisites

Software Requirements

To run the MPI application the following software installations are needed:

  • Java Development Kit (JDK) 6 (or higher)
  • Bash shell (to run the scripts)
  • Unix utilities used in the scripts: cat, curl, grep, less, sed, tail, tr
  • (Optional; if you don't want to use the embedded Container) Tomcat 7 (or higher)
  • (Optional; for a load balancer setup) A load balancer, e.g. Apache 2.2 (or higher)

Valid MPI License

MPI requires a valid license in order to be used.

You can request your license by e-mail on the following address: mpi@netcetera.ch.

Upgrade guide

When the new MPI is installed in the same directory as the old one, the embedded Tomcat will delete the extract directory (containing all the logs), as it checks for the application timestamp on startup (there is a .tomcat_executable_archive.timestamp file in the extract directory). In case the timestamps don't match, the extract directory will be deleted.

In order to perserve the logs from the previous MPI installation, you can either:

  • manually move them to another location from the .extract folder and install the new MPI in the same location
  • or, install the new MPI in a new location

Installation guide

Unzip the MPI package (mpi-package-<version>.zip) to a directory of your choice.

This will create the following directory structure rooted at $MPI_HOME:

Directory structure
-------------------
 
$MPI_HOME/                                                <-- The unzipped directory contained in the mpi-package zip file (mpi-package-<version>).
  |
  +-- bin/
  |     |
  |     +-- mpictl.sh                                     <-- Script to start/stop MPI nodes.
  |     |
  |     +-- mpitool.sh                                    <-- Script to run MPI related tools.
  |
  +-- conf/                                               <-- Sample (default) configurations used by the mpictl script and the MPI application.
  |     |
  |     +-- config.properties                             <-- Sample configuration settings
  |     |
  |     +-- ehcache.xml                                   <-- Sample session Ehcache configuration (without replication)
  |     |
  |     +-- mpi.xml                                       <-- Template MPI 3-D Secure entities configuration
  |     |
  |     +-- server-<node-ID>.xml                          <-- Sample server configuration for the MPI node's embedded Tomcat
  |
  |
  +--- currencies/
  |     |
  |     +--org/
  |         |
  |         +-- joda/
  |               |
  |               +-- money/
  |                     |
  |                     +-- MoneyDataExtension.csv        <-- Override/extend currencies and exponents            
  |
  |
  +-- doc/                                                <-- MPI documentation
  |     |
  |     +-- ...
  |
  +-- lib/                                                <-- Jar files used by the scripts and the MPI war file that can be deployed to your servlet container.
  |     |
  |     +-- mpi.war
  |     |
  |     +-- mpi-cli-tool.jar
  |     |
  |     +-- mpi-exec-war.jar
  |     |
  |     +-- perf4j.jar
  |
  +-- node-<node-ID>/                                     <-- Extract directory created by starting an MPI node via the mpictl script.
  |     |
  |     +-- logs/
  |
  +-- out/                                                <-- Directory where the Server startup logs are written to.
  |     |
        +-- catalina-<node-ID>.out
  |
  +-- pid/                                                <-- Directory where the mpictl script stores PIDs of running MPI nodes.
  |     |
  |     +-- node-<node-ID>.pid
  |
  +-- xsd/                                                <-- XML schemas used by the MPI for your reference.
        |
        +-- ...

Configuration

Create a directory $MPI_CONFIG_HOME where you can store the MPI configuration (e.g. $HOME/.mpi).

Copy the sample configuration files from $MPI_HOME/conf to $MPI_CONFIG_HOME.

Configure 3-D Secure entities

Configure your 3-D Secure entities in $MPI_CONFIG_HOME/mpi.xml. Add Schemes, Acquirers and Merchants. Refer to the MPI Configuration documentation for details about the configuration.

Configure servers

Adjust the files $MPI_CONFIG_HOME/server<node-ID>.xml to suit your needs (i.e. change connector settings if needed).

See Server Configuration for a sample configuration.

Configure MPI license

Once you have obtained the MPI license file (mpi.lic), put it in the $MPI_CONFIG_HOME where you store the MPI configuration.

For more details about the license file configuration, check the configuration of license.resourceLocation property in MPI Configuration Properties documentation.

After MPI application is started you can see your MPI license details on the Dashboard page.

Additional configuration settings

Additional configuration properties can be set via $MPI_CONFIG_HOME/config.properties.

For details on the available configuration properties consult the MPI Configuration Properties documentation.

Currencies

The MPI relies on Joda Money to validate currency codes and resolve currency exponents. Joda Money provides a default currency configuration to support this process.

The MPI allows to extend/override the default currencies and their exponents defined by Joda Money by providing a org/joda/money/MoneyDataExtension.csv file on the classpath.

Additional classpath elements can be specified using the org.apache.catalina.loader.VirtualWebappLoader in the Tomcat server configuration.

The default server.xml configuration provided by the MPI adds the following folder to the classpath: $MPI_HOME/currencies and provides the directory structure for org/joda/money/MoneyDataExtension.csv.

Currencies can be extended/overridden by adding a line in the MoneyDataExtension.csv file.

For example, in order to modify the exponent of Indonesian Rupiah (IDR) to be 2, add the following line to MoneyDataExtension.csv:

IDR,360,2,ID

Countries

The MPI comes with a default ISO 3166-1 country codes. In order to see which country codes are supported by the MPI by default, issue a HTTP GET command to http(s)://<host>:<port>/mpi/countries.

The MPI allows to extend/override the default country codes by providing a com/netcetera/country/CountriesDataExtension.csv file on the classpath.

Additional classpath elements can be specified using the org.apache.catalina.loader.VirtualWebappLoader in the Tomcat server configuration.

The default server.xml configuration provided by the MPI adds the following folder to the classpath: $MPI_HOME/countries and provides the directory structure for com/netcetera/country/CountriesDataExtension.csv.

Countries can be extended/overridden by adding a line in the CountriesDataExtension.csv file.

For example, in order to add the country code for Netherlands Antilles, add the following line to CountriesDataExtension.csv file:

Netherlands Antilles,AN,ANT,530

Startup the MPI

You can start the MPI using the mpictl script:

$ $MPI_HOME/bin/mpictl.sh -c $MPI_CONFIG_HOME start

Similarly you can stop the MPI using the following command:

$ $MPI_HOME/bin/mpictl.sh stop

Testing the installation

To check whether the MPI application is up and running, navigate to http(s)://<host>:<port>/mpi/dashboard. If everything went fine, you should see the MPI dashboard. Otherwise check your log files under $MPI_HOME/node-<node-ID>/logs for errors.

Using your own Tomcat

The MPI package contains the MPI packaged as an executable JAR file with an embedded Tomcat, so it can be started as a standalone application.

If you want to use your own Tomcat, you have to deploy the mpi.war found in the $MPI_HOME/lib directory to Tomcat.

Pass the mpi.config.home system property with a value pointing to your configuration directory (i.e. $MPI_CONFIG_HOME) when starting Tomcat.

Note: If you have stored the MPI configuration under $HOME/.mpi, setting this system property is not needed. (The MPI uses $HOME/.mpi as the default configuration directory if mpi.config.home is not set.)

The default log location when using your own Tomcat is $CATALINA_BASE/logs. Find the log files there for troubleshooting the installation.