Docs‎ > ‎

Apache Tomcat

This page contains instructions for installing 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 JDK (not JRE) 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). Please note that, if Java is installed in a path that contains one or more spaces, you will need to use the short names of those directories (e.g. PROGRA~2 instead of "Program Files"). To determine the short name of a directory, run the command dir /x from the parent directory.

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


 API Creator runs in a container.  Here we set up the container as Apache Tomcat. This procedure has been tested with Tomcat 7.x, 8.x and 9.x.

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)
Note: you can also use the MariaDB JDBC connector

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.

Using MySQL As your Administration Database

<!-- API Live Creator  -->
  <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/admin_db?characterEncoding=utf8
        username="admin_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).

Also note that, if you are using the MariaDB driver, you'll need to change the driverClassName entry's value to "org.mariadb.jdbc.Driver"

Using Apache Derby as Administration Database

Note:The Derby JAR must be in the {CATALINA_HOME}/lib directory, unless you add the derby.system.home parameter to Tomcat's Java command line.
<Resource accessToUnderlyingConnectionAllowed="true" auth="Container" defaultAutoCommit="false" driverClassName="org.apache.derby.jdbc.EmbeddedDriver" initialSize="0" logAbandoned="true" maxActive="10" maxIdle="0" maxWait="15000" minIdle="0" name="jdbc/AdminDB" removeAbandoned="true" removeAbandonedTimeout="30" timeBetweenEvictionRunsMillis="30000" type="javax.sql.DataSource" url="jdbc:derby:/Users/jdoe/CALiveAPICreatorAdmin;create=true" username="CALiveAPICreatorAdmin"/>

Using MariaDB as Administration Database

Note:The mariadb JAR must be in the {CATALINA_HOME}/lib directory.
<Resource accessToUnderlyingConnectionAllowed="true" auth="Container" defaultAutoCommit="false" driverClassName="org.mariadb.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:mariadb://localhost:3306/dblocal_admin" username="dblocal_admin" validationQuery="select 1"/>

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 CA Live API Creator

  1. Download the CA Live API Creator WAR file.
  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

Windows:
  1. Start Command Window
  2. cd toTomcat's bin directory
  3.  c:\apache-tomcat-8.0.28\bin>start startup.bat

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 Live API Server

Access API Server through your web browser:  http://localhost:8080/APICreator/index.html

When the Designer starts, it will display a login dialog.  Specify:
  • server location as http://localhost:8080/APIServer
  • 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 API Creator, 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