Install on Apache Tomcat

Prerequisite: A directory called ROOT in the tomcat/apache-tomcat-<version>/webapps directory does not exist.
lac31
You can install 
CA Live API Creator
 on Apache Tomcat Web server as an installable web application ARchive (WAR). This article includes information about how to install 
CA Live API Creator
 on a local machine running Apache Tomcat.
Use the following process to install 
CA Live API Creator
 on Apache Tomcat Web server:
 
 
3
 
 
Verify the Prerequisites
Before installing 
CA Live API Creator
 on Tomcat Web server, ensure that you have completed the following:
  • You have Tomcat installed.
    For more information about how to download and install Tomcat, see the Apache Tomcat website.
  • You have Java JDK installed.
    For more information:
    • About installing Java JDK, see the Oracle product downloads site.
    • About the version of Java JDK 
      CA Live API Creator
       supports, see Supported Platforms.
      You can verify what version of Java JDK you have installed and whether you have it installed correctly by issuing the 
      java -version
       command.
  • (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_92
    . If 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.
Configure your Admin Database
CA Live API Creator
 requires the corresponding JDBC driver to the database management system (DBMS) you use as your admin database.
 
 
Prerequisite:
 Your Tomcat service is stopped.
 You can run 
CA Live API Creator
 in Apache Tomcat using the following DBMS:
  •  
    Use MySQL (or MariaDB) as your Admin Database
    You can access a database using the MySQL JDBC driver or the MariaDB JDBC driver. The 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 want to use.
    For more information about MariaDB, see the MariaDB site.
    Verify the Prerequisites
    Before adding and configuring the MySQL (or MariaDB) JDBC driver, ensure you have completed the following:
    • 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 website. The MySQL JDBC driver is available from the MySQL site.
     Use the supported version of the MariaDB JDBC driver. The MariaDB JDBC driver version 1.5.6 has a bug which causes a NullPointerException.
    For more information about the MariaJDBC versions that 
    CA Live API Creator
     supports, see Supported Platforms.
    Create the Admin DB Schema
    Create a new MySQL schema for your admin database. In this example, the MySQL schema is named 
    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
      .
    The 
    liveapicreator_adm_db
     MySQL schema for your 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. Go to 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. Go to the Schema Privileges tab and click 
      Add Entry
      .
    4. Select 
      liveapicreator_adm_db
       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 to the 
    liveapicreator_adm_db
     MySQL schema.
     
    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:
        <!--
        CA 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
     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 versions of PostgreSQL that 
    CA Live API Creator
     supports, see Supported Platforms.
    Complete the following to 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 that you want, for example, 
    lacadmin
    .
    Create a New PostgreSQL User
    Create a new user in your PostgreSQL database (for example 
    lacuser
    ) and ensure that user has full privileges to the schema you 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 
      t
       
      omcat/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.
  • (Advanced Users) Use Apache Derby as your Admin Database.
    For more information about how to use Apache Derby as your admin database, see Configure Apache Derby as your Admin Database.
Install 
CA Live API Creator
 on Tomcat
 
Prerequisite:
 A directory called 
ROOT
 in the 
tomcat/apache-tomcat-<version>/webapps
 directory does not exist.
You can install all the 
CA Live API Creator
 components—API Creator, API Server, and Data Explorer—simultaneously or (if you are an advanced user and you want greater flexibility) each of the components individually using the WAR files that are included in the 
CA Live API Creator
 installation zip file.
 Install all the 
CA Live API Creator
 components simultaneously using the
/
development/
CALiveAPICreator.war
 file.
  1. Retrieve the
    CALiveAPICreator.war
    file from your 
    CA Live API Creator
     installation bundle and copy it to the
    %Tomcat_Home%
    /webapps
     directory.
  2. (If you want 
    CA Live API Creator
     to be at the root URL) Rename the
    CALiveAPICreator.war
    file to
    %Tomcat_Home%/webapps/ROOT.war
    .
Install an individual 
CA Live API Creator
 component using the WAR file pertaining to that component. These files are located in the 
/production
 directory.
  • Retrieve the WAR file pertaining to the component you want to install from your 
    CA Live API Creator
     bundle and copy it to the 
    %Tomcat_Home%/webapps
     directory:
    • APICreator.war
      , which installs API Creator.
    • APIServer.war
      , which installs API Server.
    • DataExplorer.war
      , which installs Data Explorer.
    You can copy one or more component WAR files into the 
    %Tomcat_Home%/webapps
     directory.
  • (If you want API Server to be at the root URL) Rename the 
    APIServer.war
     file to 
    ROOT.war
    .
Start your Tomcat Service
If you are deploying into production using a cluster or if you are scripting deployment, you can preaccept the terms of the End User License Agreement (EULA). Preaccept the EULA so that you do not have to accept it in API Creator. To preaccept the EULA, add the following system property 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. Start you Tomcat service by issuing the following command:
    sh startup.sh
    You can stop your Tomcat Service using the 
    shutdown
     command.
  3. If you encounter a permission error, issue the 
    chmod 755 catalina.sh
    command.
 
(Windows)
 
  1. From a command prompt, change directory to 
    tomcat\apache-tomcat-<version>\bin
     directory.
  2. Start you Tomcat service by issuing the following command:
    startup
The Tomcat service is started and 
CA Live API Creator
 is installed.
(Optional) Verify the Installation
  1. Verify that 
    CA 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.
     On Windows, the file may have a date in its name.
    The following response is expected:
    Start Server startup in <miliseconds> ms
     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. A wrong version of Tomcat can execute. Ensure that a previous version of a Tomcat install on Windows is not set to an environmental variable. A good indicator is that there are no files in the 
    tomcat/apache-tomcat-<version>/logs
     folder.
    If WARNING messages from the 
    StandardJarScanner
     appear, you can safely ignore them. These messages are not errors.
Optional Configuration
The following topic provides optional configuration details.
The following optional configuration requires that you restart your Tomcat service after you configure.
Minimize Security Vulnerabilities by Enabling HTTP Security Headers
You can minimize security vulnerabilities on 
CA Live API Creator
 applications, such as API Creator and Data Explorer, which are web-based applications, by adding security headers to Tomcat. HTTP security headers give browsers explicit instructions about how to communicate with a website. 
You can minimize security vulnerabilities on 
CA Live API Creator
 applications at one of the following levels: 
  • At the Java-container level, within Tomcat.
  • At the 
    CA Live API Creator
     application-level, within the 
    WEB-INF/web.xml
     file that is in the 
    /development/CALiveAPICreator.war
     file. The 
    WEB-INF/web.xml
     file contains the web application deployment descriptor for your application.
The following procedure details how to minimize security vulnerabilities on 
CA Live API Creator
 applications within Tomcat.
 
Follow these steps:
 
  1. Open the 
    conf/web.xml
     file.
  2. Instruct Tomcat to support the HTTP Header Security filter by uncommenting the following section:
    <filter>
    <filter-name>httpHeaderSecurity</filter-name>
    <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
    <async-supported>true</async-supported>
    </filter>
  3. Add the following section to the file, customizing the URL for API Creator and Data Explorer:
    <filter-mapping>
    <filter-name>httpHeaderSecurity</filter-name>
    <url-pattern>/
    APICreator/*
    </url-pattern>
    <url-pattern>/
    DataExplorer/*
    </url-pattern>
    </filter-mapping>
    This configuration ensures that the REST calls that API Server facilitates are not affected with these security headers that would add overhead to the REST responses.
You have protected 
CA Live API Creator
 applications at the Java-container level.
Next Steps
Log in to 
CA Live API Creator
 
You can access the 
CA 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 in 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.
Import the API Server License
The API Server license controls access to API Creator and services.
  1. Log in to API Creator as the system administrator (
    sa
    ).
  2. Click the 
    License
     tab.
    The License page appears. 
  3. Click 
    Upload License
    .
    A file selection dialog opens.
  4. Locate and select the license file that you received from CA Technologies, and then click 
    OK
    .
The API Server license is imported and displays on the License page.
Install the Admin CLI
Install the Admin command-line interface (CLI) and its dependencies (Node.js) if you want to manage your 
CA Live API Creator
 installation from the command line or using scripts. You can do things such as migrate APIs–including your JavaScript user libraries, resources, authentication providers, API Gateway definitions–to a newer version of API Server using the Admin CLI.
For more information:
Begin your Exploration of the API Samples
Begin your exploration of the API samples.
For more information about these samples, see Tutorials and Samples.
Advanced Configuration
The following topics provide advanced configuration details.
Access URLs That Contain Special Characters
If your database contains binary primary keys, you can access certain URLs that contain special characters, such as slash (/), by setting the following configuration parameters to 
true
 in your your Tomcat installation:
  •  
    org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH
     
  •  
    org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH
     
You can add these configuration parameters to your Tomcat's startup script using the following options:
-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
-Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
Allow Multipart/Form-Data Requests to be Parsed Automatically
You can allow multipart/form-data requests to be parsed even when the target servlet doesn't specify 
@MultipartConfig
 or have a 
<multipart-config>
 element.
  1. Open the 
    tomcat/apache-tomcat-<version>/conf/context.xml
     file and insert the following XML code within the 
    <Context>
     tag:
    allowCasualMultipartParsing="true"
  2. Save your changes, and then close the file.