Installing‎ > ‎

Install on Apache Tomcat

You can install Live API Creator on Apache Tomcat Web server as an installable Web application ARchive (WAR). The following procedures are for installing on a local machine.

Verify Prerequisites

Prerequisites: 

  • You have Java JDK 8 or greater installed.
For more information:

Tip! You can check what version of Java JDK you have installed and whether you have it installed correctly by issuing the following command:

java -version
  • (On Windows) You have created a JAVA_HOME environment variable that has a variable value to the location of your Java JDK installation. For example, JAVA_HOME with C:\Program Files\Java\jdk1.8.0_92If Java is installed in a path that contains one or more spaces, use the short names of those directories for the variable value (for example, PROGRA~2 instead of Program Files).

This setting is in effect after you open a new Command window.

  • You have Tomcat installed. For more information about downloading and installing Tomcat, see the Apache Tomcat site.

Configure your Admin Database

Prerequisite: Your Tomcat service is stopped.

You can run Live API Creator in Apache Tomcat using the following database management systems as your admin database:
  • MySQL or MariaDB.
  • PostgreSQL.

Note: If you use a PostgreSQL version prior to 9.4, you cannot specify the schema. The admin data goes into the public schema.

For more information about the supported versions of PostgreSQL, see Supported Platforms.

  • (Advanced Users) Apache Derby.

Use MySQL (or MariaDB) as your Admin Database

You can use the MySQL JDBC driver or you can use the MariaDB JDBC driver. MariaDB JDBC driver is compatible with MySQL. Add the MariaDB JDBC driver to avoid optimistic locking failures. Complete the following procedures based on the driver type you choose.

For more information about MariaDB, see the MariaDB site.

Verify the Prerequisite

Verify the following prerequisite before adding and configuring the MySQL (or MariaDB) JDBC driver:

  • You have MySQL installed. For more information about downloading MySQL, see the MySQL download site.
  • (Recommended) You have MySQL Workbench installed. For more information about installing MySQL Workbench, see MySQL Workbench.

Add the MySQL (or MariaDB) JDBC Driver

Add either the MariaDB JDBC driver or the MySQL JDBC driver to the {CATALINA_HOME}/lib directory. The MariaDB driver is available from the MariaDB site. The MySQL JDBC driver is available from the MySQL site.

Create the Admin DB Schema

Create a new MySQL schema (named, for example, liveapicreator_adm_db).
    1. In MySQL Workbench, connect to your database.
    2. Right-click the existing schema and select Create Schema:.
    3. Name your schema liveapicreator_adm_db and then click Apply.
A new schema for the admin database is created.

Create a New MySQL User

    1. In MySQL Workbench, from the Management section, click Users and Privileges, and click Add Account.
    2. On the Login tab, enter a name for your new MySQL user using the following details, and then click Apply:
      Login Name
      Enter lac_dbadm.
      Limit Connectivity to Hosts Matching
      (If you plan to run Tomcat on the same machine as MySQL) Enter localhost.
      Password
      Enter password!.
    3. On the Schema Privileges tab, click Add Entry.
    4. Choose 'lac_dbadm' as the selected schema, and then click Ok.
    5. Click Select ALL to select all the access rights, clear the GRANT OPTION access right, and then click Apply.
The new MySQL user is created and granted access rights.

Configure Tomcat for MySQL

Configure the Tomcat container with JNDI settings and server data source configuration.
      1. Open the tomcat/apache-tomcat-<version>/conf/context.xml file and insert the following XML code within the <Context> tag, save your changes, and close the file:
        <ResourceLink global="jdbc/AdminDB" name="jdbc/AdminDB" type="javax.sql.DataSource"/>
      2. Open the tomcat/apache-tomcat-<version>/conf/server.xml file and complete the following:
        1. Insert the following XML code within the <GlobalNamingResources> tag:
          <!-- Live API Creator -->
          <Resource accessToUnderlyingConnectionAllowed="true" 
          auth="Container" 
          defaultAutoCommit="false" 
          driverClassName="com.mysql.jdbc.Driver" 
          initialSize="5" 
          logAbandoned="true" 
          maxTotal="20" 
          maxIdle="10" 
          maxWaitMillis="30000" 
          minIdle="5" 
          name="jdbc/AdminDB" 
          password="password!" 
          removeAbandonedOnMaintenance="true" 
          removeAbandonedTimeout="30" 
          type="javax.sql.DataSource"
          url="jdbc:mysql://localhost:3306/liveapicreator_adm_db?characterEncoding=utf8" 
          username="lac_dbadm" 
          validationQuery="select 1"/>
        2. Update the username and password to the MySQL user you created.
        3. If your MySQL does not use UTF-8 by default, add the characterEncoding=utf8 parameter to the url parameter.
        4. Save your changes and close the file.
The MySQL JDBC driver is configured.

Configure Tomcat for MariaDB

  1. Open the tomcat/apache-tomcat-<version>/conf/context.xml file and insert the following XML code within the <Context> tag, save your changes, and close the file:
    <ResourceLink global="jdbc/AdminDB" name="jdbc/AdminDB" type="javax.sql.DataSource"/>
  2. Open the tomcat/apache-tomcat-<version>/conf/server.xml file and complete the following:
    1. Insert the following XML code within the <GlobalNamingResources> tag:
      <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/liveapicreator_adm_db?characterEncoding=utf8"
      username="lac_dbadm"
      validationQuery="select 1"/>
    2. Update the username and password to the MariaDB user you created.
    3. On systems that are not set to UTC, modify the MySQL connection string to work around timestamp issues.
    4. If your MariaDB does not use UTF-8 by default, add the characterEncoding=utf8 parameter to the url parameter.
    5. Save your changes and close the file.
The MariaDB JDBC driver is configured.

    Use PostgreSQL as your Admin Database

    Verify the Prerequisite

    Verify that you have a PostgreSQL server installed and it is running before adding and configuring the PostgreSQL JDBC driver.

    Add the PostgreSQL JDBC Driver

    Add the PostgreSQL JDBC driver to the tomcat/apache-tomcat-<version>/lib directory.

    For more information about how to add the driver, see the PostgreSQL site.

    Create the Admin DB Schema

    Create a schema in your PostgreSQL database. You can call it anything you want, for example, lacadmin.

    Create a New PostgreSQL User

    Create a new user in your PostgreSQL database (for example lacuser) and make sure that user has full privileges to the schema you just created.

    Configure Tomcat for PostgreSQL

    1. Open the tomcat/apache-tomcat-<version>/conf/context.xml file and insert the following XML code within the <Context> tag, save your changes, and close the file:
      <ResourceLink global="jdbc/AdminDB" name="jdbc/AdminDB" type="javax.sql.DataSource"/>
    2. Open the tomcat/apache-tomcat-<version>/conf/server.xml file and insert the following code in the <GlobalNamingResources> tag:
      <Resource accessToUnderlyingConnectionAllowed="true"
      auth="Container"
      defaultAutoCommit="false"
      driverClassName="org.postgresql.Driver"
      initialSize="10"
      logAbandoned="true"
      maxIdle="0"
      maxTotal="500"
      maxWaitMillis="15000"
      minIdle="0"
      name="jdbc/AdminDB"
      password="secret"
      removeAbandonedOnMaintenance="true"
      removeAbandonedTimeout="30"
      timeBetweenEvictionRunsMillis="30000"
      type="javax.sql.DataSource"
      url="jdbc:postgresql://mypostgres:5432/postgres?currentSchema=lacadmin&amp;characterEncoding=utf8"
      username="lacuser"
      validationQuery="select 1"/>

    The PostgreSQL JDBC driver is configured.

    Use Apache Derby as your Admin Database

    You can use Apache Derby as your Admin database.

    For more information about using Apache Derby as your admin database, see Configure Apache Derby as your Admin Database.

    Install Live API Creator

    Prerequisite: Ensure that there is not a directory called ROOT in the tomcat/apache-tomcat-<version>/webapps directory. If there is, delete or rename it.

    The Live API Creator installation zip file includes several WAR files that you can use to install Live API Creator. You can install all the Live API Creator componentsAPI Creator, API Server, and Data Explorerat the same time or (if you an advanced user and you want greater flexibility) each of the components individually.

    Install all the components at the same time using the CALiveAPICreator.war file. This file is located in the /development directory.

    1. Retrieve the CALiveAPICreator.war file from your Live API Creator installation bundle and copy it to the tomcat/apache-tomcat-<version>/webapps directory.
    2. (If you want Live API Creator to be at the root URL) Rename the CALiveAPICreator.war file to tomcat/apache-tomcat-<version>/webapps/ROOT.war.

    Install an individual Live API Creator component using the WAR file pertaining to that component. These files are located in the /production directory.

    Note: You can copy one or more component WAR files into the tomcat/apache-tomcat-<version>/webapps directory.

    1. Retrieve the WAR file for the component you want to install from your Live API Creator bundle and copy it to the tomcat/apache-tomcat-<version>/webapps directory:
      • APICreator.war, which installs API Creator.
      • APIServer.war, which installs API Server.
      • DataExplorer.war, which installs Data Explorer.
    2. (If you want API Server to be at the root URL) Rename the APIServer.war file to ROOT.war.

    Upgrade to a Newer Version of Live API Creator

      1. Stop the Tomcat service.
      2. In the tomcat/apache-tomcat-<version>/webapps directory, delete the ROOT.war file and the ROOT folder.
      3. Copy the /development/CALiveAPICreator.war file to ROOT.war. Retain the original to recall the version number.
      4. Copy ROOT.war into the Tomcat webapps directory.

    Start your Tomcat Service

    Note: If you are deploying into production using a cluster or if you are scripting deployment, you can pre-accept the terms of the End User License Agreement (EULA) so that you do not have to accept it in API Creator by adding the following argument to the Java command line for Tomcat (or any other Java container):

    -Dca_accept_license=ENU

    (Mac/Unix)

    1. From Terminal, cd to Tomcat's bin directory.
    2. Issue the following command:
      sh startup.sh
      Note: You can stop your Tomcat Service using the shutdown command.
    3. If you encounter a permission error, issue the following command:
      chmod 755 catalina.sh
    (Windows)
    1. From a command prompt, change directory to tomcat\apache-tomcat-<version>\bin directory.
    2. Issue the following command:
      startup

    The Tomcat service is started and Live API Creator is installed.

    (Optional) Check the Logs

    1. Verify that Live API Creator installed correctly and that there are no exceptions by checking the logs. Using a text editor, open the tomcat/apache-tomcat-<version>/logs/catalina.out file.
      Note: On Windows, the file may have a date in its name.

      The following response is expected:

      Start Server startup in <miliseconds> ms
      Important! If you see an error and the server does not start properly, fix the error then stop and restart the server by issuing the following commands:
      shutdown
      startup
    2. Verify you are running the configured Tomcat by checking the Tomcat command window. Ensure that a previous version of a Tomcat install on Windows is not set to an environmental variable that results in executing the wrong version of Tomcat. A good indicator is that there are no files in the tomcat/apache-tomcat-<version>/logs folder.
    Note: If WARNING messages from the StandardJarScanner appear, you can safely ignore them. These messages are not errors.

    Log on to Live API Creator

    You can access the Live API Creator component WARs you have copied to the tomcat/apache-tomcat-<version>/webapps directory using a URL that includes the WAR file's name. For example, if you have copied the DataExplorer.war file into this directory, you can access Data Explorer using the following URL:

    http://localhost:8080/DataExplorer

    To log on to API Creator, enter the following URL into a browser window:

    http://localhost:8080/APICreator

    For more information about logging on to API Creator, see Create your API Project.

    Verify the Installation

    Verify the installation and begin your exploration of the samples. If required, install the API Server license.

    For more information about installing this license, see Server License.