Installing Espresso on Tomcat

Espresso is provided in a number of alternatives: 
  • Cloud-based service - runs on AWS or Azure. No install. 
  • Appliance - VMware image, or Docker. Install the VM, and run.  Described here.
  • Installable web app (war) - for deployment into Web / App Servers, so it can run with and utilize your existing systems, with a familiar deployment model. 
This page contains instructions for installing Espresso as a WAR file on Apache Tomcat.  They are targeted to your own environment.

To deploy the war to the cloud:

Prerequisites

Java 7.x or higher 

Verify you have Java 7 or higher, by using a Command Line, and typing:

java -version


On Windows, you may also need to set your environment variable.  Use Control Panel > System > Advanced, and specify the location of your Java installation (see screenshot).


Note - this setting will be in effect only once you open a new Command Window.



Configure MySQL

Install MySQL

If you don't have it already, install MySQL (link here).

If you don't have it already, install MySQL Workbench.  This will be useful in the configuration steps below, but is not strictly speaking required.


Create Admin DB Schema

Create a new MySQL schema (e.g., espresso_adm_db): in MySQL Workbench, right-click on the existing schemas, and create a new schema:


Create a new MySQL user

  1. In MySQL Workbench, in the left NavBar, click Management > Users and Privileges, and create a user as shown below
  2. You can choose any name, but the following work with the configuration scripts:
    1. User: espresso_adm_usr
    2. Password: password!

The schema privileges for this new user should be as follows:



Configure Tomcat


Espresso runs in a container.  Here we set up the container as Apache Tomcat.

Install Apache Tomcat 


  1. Download Tomcat (link here). It should be about 10MB, a file named something like apache-tomcat-7.0.61.zip.
  2. Unzip this file. 
    1. The path where you unzip this file should not contain spaces
    2. This will create a directory named something like apache-tomcat-7.0.61 (or whatever the version is). 
We will refer to this as the Tomcat directory.  An example is shown here:



Configure the MySQL JDBC driver

  1. Download the MySQL JDBC connector.  
    1. Select the Platform Independent option, zip format
    2. That will download a file like mysql-connector-java-5.1.35.zip.
  2. Unzip this file to obtain the jar file
  3. Copy the file mysql-connector-java-5.1.35-bin.jar to the lib directory in the Tomcat directory (note: the exact version number may vary)


Configure the conf/server.xml file


In your Tomcat directory, edit conf/server.xml, and 
  1. insert the Resource tag (the xml code below) within the <GlobalNamingResources> tag
    • See the screen shot, below.
  2. Update the username and password to the MySQL user created, above.

<!-- ESPRESSO  -->
  <Resource accessToUnderlyingConnectionAllowed="true" 
        auth="Container" 
        defaultAutoCommit="false" 
        driverClassName="com.mysql.jdbc.Driver" 
        initialSize="5" 
        logAbandoned="true" 
        maxActive="20" 
        maxIdle="10" 
        maxWait="30000" 
        minIdle="5" 
        name="jdbc/AdminDB" 
        password="password!" 
        removeAbandoned="true" 
        removeAbandonedTimeout="30" 
        type="javax.sql.DataSource"
url="jdbc:mysql://localhost:3306/espresso_adm_db?characterEncoding=utf8
        username="espresso_adm_usr" 
        validationQuery="select 1"/>

Please note that the url parameter must include the characterSet=utf8 parameter (technically, that's not required if your MySQL uses UTF-8 by default, but this is just to be safe).

Configure the conf/context.xml file

Edit the indicated file and
  1. insert the xml code below within the <Context> tag
<ResourceLink global="jdbc/AdminDB" name="jdbc/AdminDB" type="javax.sql.DataSource"/>


Here is a screen shot illustrating the steps above.



Install Espresso Logic

  1. Download the Espresso WAR file here.
  2. Move that file to the webapps directory in the Tomcat directory and rename it to ROOT.war


Start Tomcat

Start your tomcat service:

Mac / Unix:
  1. cd to Tomcat's bin directory
  2. sh startup.sh

PC:
  1. Start Command Window
  2. cd toTomcat's bin directory
  3.  startup

Note: if you encounter a permission error on Mac or Unix:
chmod 755 catalina.sh



Check the Logs

Use a text editor to open logs/catalina.out, shown at right.

Note: on Windows, that file may have a date in its name.

Don't forget - if you make an error and the server does not start properly, you probably need to stop / restart it.


Verify Tomcat install

A note of caution - check the Tomcat command window to verify you are running the configured Tomcat.  

We have seen instances where a previous version of a Tomcat install on Windows set an environmental variable that results in executing the wrong version of Tomcat.  A good indicator is "no files in the logs folder".


Start Espresso

Access Espresso through your web browser:  http://localhost:8080/LogicDesigner/index.html

When the Designer starts, it will display a login dialog.  Specify:
  • server location as http://localhost:8080
  • user: admin
  • password: Password1

WAIT about 1 minute while the repository is being configured the first time.


Verifying the Installation


Please verify the installation, and begin your exploration of the samples, with the procedure below.

Installing the license

You may need to import a install a license as described here.

Create Northwind (and run Tour)

Once you are in the Espresso Logic Designer, use the left navbar  REST API  >> Create.. (a new API / Project), using the default version of Northwind.  Verify that the basic operations operate - Get requests, new resources, rules, Live Browser.

Import Sample Databases

The documentation is created around the Logic Demo and Logic Sample databases.  Create them as described here.


Stop Tomcat


Use the same commands as for starting Tomcat, but shutdown instead of Startup.


Upgrading


To upgrade to a newer version of the war:

  1. If it is running, shutdown the server
  2. In the Tomcat webapps directory, delete...
    1. ROOT.war
    2. ROOT folder
  3. Copy the new war to ROOT.war (retain the original to recall the version number)
  4. Copy ROOT.war into the Tomcat webapps directory
  5. Startup the server