Install on Apache Tomcat

Install on Apache Tomcat
You can install
Layer7 Live API Creator
on Apache Tomcat Web server as an installable web application ARchive (WAR). This article includes information about how to install
Layer7 Live API Creator
on a local machine running Apache Tomcat.
Use the following process to install
Layer7 Live API Creator
on Apache Tomcat Web server:
3
Verify the Prerequisites
Before you install
Layer7 Live API Creator
on Tomcat Web server, ensure that you have completed the following prerequisite steps:
  • You have installed Tomcat.
    For more information about how to download and install Tomcat, see the Apache Tomcat website.
  • You have installed the Java Development Kit (JDK) version that
    Layer7 Live API Creator
    supports.
    For more information:
  • You have created a
    JAVA_HOME
    environment variable and set the value to point to the JDK installation directory.
    If you have not already done this, complete the following based on your operating system:
    (Windows)
    Set the value for the
    JAVA_HOME
    environment variable as the path to your JDK installation. If you did not change the path during installation, it is something like
    C:\Program Files\Java\jdk1.8.0_92
    . If the path contains spaces, use the shortened path name, for example,
    C:\PROGRA~2\Java\jdk1.8.0_92
    . Close and re-open any command line windows that you had open before you made these changes, since you cannot reload environment variables from an active command prompt. If the changes do not take effect after reopening the command window, restart Windows.
    (Mac)
    From terminal, set the
    JAVA_HOME
    environment variable using the following command:
    export JAVA_HOME=/Library/Java/Home
  • You know the license type that you are using
    Layer7 Live API Creator
    under, either a standard license that the CA Support site issues or an Enterprise Software Portfolio License Agreement (PLA).
    For more information about licensing, see Licensing.
  • You have reviewed the installation best practices.
    For more information about the best practices, see Installation Best Practices.
(Optional) Bundle the Admin Repository into the WAR File
You can bootstrap
Layer7 Live API Creator
with a specific configuration for your API metadata by bundling the admin repository into the
CALiveAPICreator.war
file. For example, you have configured
Layer7 Live API Creator
in your development environment, and you want to include this configuration in the WAR file and deploy it to a server.
If you are persisting the authentication tokens that
Layer7 Live API Creator
dynamically generates by way of an authentication database, you can also bundle the definition of the data source for the authentication token database (the
ApiKey.json
file) into the WAR file.
You can bundle the admin repository and the definition of the data source for the authentication token database into the WAR file using a script. For more information about using this scripting method, see Example: Deploy the Bundled WAR to a Cluster.
Prerequisite:
If you are licensed to use
Layer7 Live API Creator
under a PLA, you have verified that the admin repository includes the
system/telemetry.json
file and that it is configured to collect and send
Layer7 Live API Creator
-specific usage data.
You can also activate
Layer7 Live API Creator
and configure it to send usage data after you have started API Server. For more information, see Activate and Configure to Send Usage Data.
For more information:
Follow these steps:
  1. Create the
    WEB-INF/classes
    directory.
  2. Create the
    configuration.zip
    file from your admin repository (the
    teamspaces
    and
    system
    directories).
    For more information about these directories, see View your API Definition.
  3. Copy the following files to the
    WEB-INF/classes
    directory:
    • The
      configuration.zip
      file.
    • (Optional) The
      ApiKey.json
      file for your environment.
  4. From the command line window, bundle the files that are in the
    WEB-INF
    directory into the WAR file by issuing the following command:
    jar uvf <war file> WEB-INF
    Step 3 of the sample script bundles these files into the WAR file.
The admin repository (and optionally the definition of the data source for the authentication token database) is added to the
CALiveAPICreator.war
file.
Install on Tomcat
You can:
Prerequisite:
The
${CATALINA_HOME}/webapps/ROOT
directory does not exist. If this directory exists, delete or rename it.
Install the
Layer7 Live API Creator
Components Simultaneously
Follow these steps:
  1. Retrieve the
    development/CALiveAPICreator.war
    file from your
    Layer7 Live API Creator
    installation bundle and copy it to the
    ${CATALINA_HOME}/webapps
    directory.
  2. (If you want
    Layer7 Live API Creator
    to be at the root URL) Rename the
    CALiveAPICreator.war
    file to
    ${CATALINA_HOME}/webapps/ROOT.war
    .
Install an Individual
Layer7 Live API Creator
Component
The WAR file pertaining to an individual component are located in the
/production
directory.
Follow these steps:
  1. Retrieve the WAR file pertaining to the component that you want to install from the
    production
    directory and copy it to the
    ${CATALINA_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
    ${CATALINA_HOME}/webapps
    directory.
  2. (If you want API Server to be at the root URL) Rename the
    APIServer.war
    file to
    ROOT.war
    .
(Optional) Verify your Installation
  1. Verify that
    Layer7 Live API Creator
    installed correctly and that there are no exceptions by checking the logs. Using a text editor, open the
    ${CATALINA_HOME}/logs/catalina.out
    file.
    If you are using Windows, the file might 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:
    (Windows)
    shutdown
    startup
    (Unix/Mac)
    sh shutdown.sh
    sh startup.sh
  2. Verify that 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
    ${CATALINA_HOME}/logs
    folder.
    If you receive WARNING messages from the
    StandardJarScanner
    , you can safely ignore them. These messages are not errors.
You have verified your installation.
Optional Configuration
The following topics provide optional configuration details.
The following optional configurations require that you restart your Tomcat service after you configure.
Configure Tomcat for the Northwind Sample Database
Complete the following if you want to allow application developers who use
Layer7 Live API Creator
to use the Northwind sample database.
Prerequisite:
The Northwind sample database is a Derby data source. Ensure that the correct version of the JavaDB/Apache Derby JDBC driver is in the
${CATALINA_HOME}/lib
directory. For more information about the version of JavaDB/Apache Derby JDBC driver that
Layer7 Live API Creator
supports, see Installation Requirements and Supported Platforms.
Follow these steps:
  1. Copy the
    <
    Layer7 Live API Creator
    download package>Samples/databases/Northwind.zip
    file to a directory on the same machine as Tomcat by issuing the following commands:
    In the following example, the location is
    /opt/ca/sampleDBs
    .
    cp Northwind.zip /opt/CA/lac/sampleDBs
    cd /opt/ca/sampleDBs
  2. Unzip the copied zip file into the
    Northwind
    directory by issuing the following command:
    unzip -d Northwind Northwind.zip
    The new
    Northwind
    (the case is important) directory now contains a few files and directories such as
    log
    ,
    seg0
    , etc. We recommend that you keep the zip file in this location so that you can easily restore the Northwind database to a pristine state.
  3. Instruct Tomcat to use the
    /opt/ca/sampleDBs
    directory as the default Derby directory by setting the
    derby.system.home
    system property to the
    /opt/ca/sampleDBs
    .
    There are many ways to change the value for this system property. If you are not sure how to do it, the easiest way is to set an environment variable before starting Tomcat by issuing the following command:
    export CATALINA_OPTS=-Dderby.system.home="/opt/ca/sampleDBs"
    ./startup.sh
The Northwind sample database is installed.
Speed Up Tomcat
You can speed up the time it takes Tomcat to start by specifying which JAR files Tomcat should not scan for configuration information when you use the
JarScanner
functionality. On a basic Tomcat installation, specifying Tomcat to skip unneeded JARs can reduce its startup time from 40 seconds to 4 seconds and prevents warnings.
Open the
${CATALINA_HOME}/conf/catalina.properties
file and add the following JARs to the
tomcat.util.scan.StandardJarScanFilter.jarsToSkip
JAR scanning property:
cdata*.jar,db2*.jar,derby*.jar,mariadb*.jar,mongo*.jar,mysql*.jar,\ ojdbc*.jar,postgres*.jar,sqljdbc*.jar,\ guava*.jar,mchange*.jar,mvel*.jar,quartz*.jar,shiro*.jar,slf4j*.jar,\ kafka*.jar,org.eclipse.paho.client*.jar,ecj*.jar,el-api.jar
Configure
Layer7 Live API Creator
to Access URLs That Contain Special Characters
You can:
Configure Databases that Contain Binary Primary Keys to Access URLs that Contain Special Characters
You can configure your database that contains binary primary keys to access URLs that contain special characters, such as slash (/), by adding the following configuration parameters and setting them to
true
when you start Tomcat:
org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH
org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH
For example:
-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true
-Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true
Configure
Layer7 Live API Creator
to Access URLs that Contain Special Characters
You can configure
Layer7 Live API Creator
to allow special characters, such as an opening curly brace ({), a closing curly brace (}), or a vertical bar (|), in URLs.
Complete
one
of the following:
  • If you are calling Free SQL resources with query parameters, URL-encode the query parameters.
    For more information about how to encode your URL using the syntax in
    Layer7 Live API Creator
    , see Define Free SQL Resource Types.
    For an example of how to encode your URL using a tool, see URL Encode/Decode tool site.
  • Open and configure one of the following configuration files in your Tomcat Java container based on the version of Tomcat that you have installed:
    • The
      server.xml
      configuration file.The following example configures Tomcat to accept the {, }, and | special characters in the URL requests it receives:
      <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443"
      relaxedQueryChars="{}|"/>
    • The
      ${CATALINA_HOME}/conf/catalina.properties
      configuration file.
      The following example configures Tomcat to accept the {, }, and | special characters in the URL requests it receives:
      tomcat.util.http.parser.HttpParser.requestTargetAllow={}|
Allow Multipart/Form-Data Requests to be Parsed Automatically
You can allow multipart/form-data requests to be parsed even when the target servlet does not specify
@MultipartConfig
or have a
<multipart-config>
element.
Follow these steps:
  1. Open the
    ${CATALINA_HOME}/conf/context.xml
    configuration file and insert the following XML code within the
    <Context>
    tag:
    allowCasualMultipartParsing="true"
  2. Save your changes, and then close the file.
You have allowed multipart/form-data requests to be parsed.
Configure External Logging
You can create a logger for externalizing your API logs.
For more information, see External Logging.
Minimize Security Vulnerabilities by Enabling HTTP Security Headers
You can minimize security vulnerabilities on
Layer7 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
Layer7 Live API Creator
applications at one of the following levels:
  • At the Java-container level, within Tomcat.
  • At the
    Layer7 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
Layer7 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>
    For more information about the options for the HTTP Header Security filter, see the Tomcat documentation.
    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
Layer7 Live API Creator
applications at the Java-container level.
Next Steps
Complete the following procedures after you have installed
Layer7 Live API Creator
on Tomcat.
Enable Other Options at Server Startup
The following are options that you can enable at startup:
Add these options before starting your server only once. Do not add these options as part of normal operations.
For more information about these options and other options that you can add when you start API Server, see API Server Startup Options.
Bypass the Extra Step at Login to Accept the EULA
If you are deploying into production using a cluster or if you are scripting deployment, you can bypass the API Creator screen that asks the initial API developer (a TeamSpace user) to log in to accept the user license, which pre-accepts the terms of the EULA. You can pre-accept the terms of the EULA by adding the
CA_ACCEPT_LICENSE
option when you start API Server, for example:
<...Tomcat startup...> -DCA_ACCEPT_LICENSE=ENU
Specify an Alternate License File
If you are licensed to use
Layer7 Live API Creator
under a standard license, the first time that you start Tomcat with
Layer7 Live API Creator
, you must install the API Server license file. You can install this file when you start your Tomcat service by adding the
LAC_DEFAULT_LICENSE_FILE
option when you start API Server, for example:
<...Tomcat startup...> -DLAC_DEFAULT_LICENSE_FILE=/Users/jdoe/License.txt
Change the Initial Password for the System Administrator User and for the Initial API Developer
If you did not change the initial passwords for the system administrator (
sa
) user and for the initial API developer (a TeamSpace user) for the default TeamSpace as options when you started your Java container, change the passwords. Add the
LAC_INITIAL_SA_PASSWORD
and the
LAC_INITIAL_ADMIN_PASSWORD
options when you start API Server, for example:
<...Tomcat startup...> -DLAC_INITIAL_SA_PASSWORD=<MySAPassword>
For more information:
Specify the Location from Where you Want
Layer7 Live API Creator
to Pull your Admin Repository
By default, at initial server startup,
Layer7 Live API Creator
pulls your admin repository from the location you set using the
LAC_REPOSITORY_ROOT
option. You can change this location by adding the
LAC_REPOSITORY_CONFIGURATION_URL
option when you start API Server, for example:
<...Tomcat startup...> -DLAC_REPOSITORY_CONFIGURATION_URL= https://s3-us-west-1.amazonaws.com/mybucket/myRepository.zip
Specify the Location to Where you Want
Layer7 Live API Creator
to Add your Admin Repository
The first time that you start Tomcat with
Layer7 Live API Creator
, you must set the location for your admin repository at startup by adding the
LAC_REPOSITORY_ROOT
option when you start API Server, for example:
<...Tomcat startup...> -DLAC_REPOSITORY_ROOT=${HOME}/CALiveAPICreator.repository
You can change the location by adding this option when you start API Server.
Start your Tomcat Service
  1. From Terminal or a command prompt, navigate to the
    ${CATALINA_HOME}/bin
    directory.
  2. Follow the steps based on your operating system:
    • (Mac/Unix)
      Do the following:
      1. Issue the following command:
        sh startup.sh
        If you are licensed to use
        Layer7 Live API Creator
        under a standard license and this is the first time that you start Tomcat with
        Layer7 Live API Creator
        , you must install your license for
        Layer7 Live API Creator
        .
        For more information about licenses, see Licensing.
        You can stop your Tomcat Service using the
        shutdown
        command.
      2. If you encounter a permission error, issue the following command:
        chmod 755 catalina.sh
    • (Windows)
      Do the following:
      1. From a command prompt, change directory to
        ${CATALINA_HOME}\bin
        directory.
      2. Issue the following command:
        startup
The Tomcat service is started and
Layer7 Live API Creator
is installed.
Log in to API Creator
You can access the
Layer7 Live API Creator
component WAR files that you have copied to the
${CATALINA_HOME}/webapps
directory using a URL that includes the name of the WAR file. For example, if you are have copied the
DataExplorer.war
file into this directory, you can access Data Explorer using the following URL:
http://localhost:8080/DataExplorer
Follow these steps:
  1. Enter the following URL into a browser window:
    http://localhost:8080/APICreator
    The API Creator logon authentication dialog opens.
  2. Complete the following fields, and then click
    Login
    :
    If the
    default
    TeamSpace is the only TeamSpace that exists, you are the initial TeamSpace user, and you are new to using API Creator, the user name for this user is
    admin
    .
    Server
    The URL and location of API Server, which can include the root web application archive (WAR) file's name.
    Example:
    /APIServer
    The server location and name depends on the type of installation and configuration of your API.
    Username
    The username for the initial API developer that
    Layer7 Live API Creator
    creates when you install
    Layer7 Live API Creator
    , which is
    admin
    . Enter
    admin
    .
    Password
    The password for the initial API developer. Enter
    Password1
    .
  3. If this is your first time logging in to API Creator, accept the terms of the EULA. You must accept these terms before you can use API Creator.
You are logged in to API Creator as the administrator user (admin).
Configure
Layer7 Live API Creator
to Collect and Send Usage Data
If you are licensed to use
Layer7 Live API Creator
under a PLA, you must activate
Layer7 Live API Creator
and configure it to collect and send usage data. If you are licensed to use
Layer7 Live API Creator
under a standard license, you can consent to
Layer7 Live API Creator
collecting and sending telemetry data, or system and usage data.
For more information about how to configure to collect and send usage data, see Activate and Configure to Send Usage Data.
Import the API Server License
The API Server license controls access to API Creator and services. If you are licensed to use
Layer7 Live API Creator
under a standard license and you did not install the API Server license file when you started Tomcat (by adding the
LAC_DEFAULT_LICENSE_FILE
option at API Server startup), you must now upload it.
For more information about licensing, see Licensing.
Install the Admin CLI
If you want to manage your
Layer7 Live API Creator
installation from the command line or using scripts, install the Admin command-line interface (CLI). With the Admin CLI installed, you can manage your admin services, such as migrating APIs–including your JavaScript user libraries, resources, authentication providers, and API Gateway definitions–to a newer version of
Layer7 Live API Creator
.
For more information:
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.
Configure to Run as a Cluster
You can configure
Layer7 Live API Creator
for scalability and increased performance by configuring it to run as a cluster within multiple nodes.
For more information about how to configure
Layer7 Live API Creator
to run as a cluster, see Configure to Run as a Cluster.
Create a Database for your Authentication Tokens
By default,
Layer7 Live API Creator
generates authentication tokens, stores them in the in-memory Derby database, and synchronizes them to your admin repository in the following cases:
  • You have configured
    Layer7 Live API Creator
    to run as a single node.
  • You are running in a local development environment.
  • You have specified an authentication provider that uses the
    Default Auth Provider
    authentication method (for example, the
    built-in authentication
    authentication provider) or a custom JavaScript authentication provider that uses the
    JavaScript Auth Provider
    authentication method as the authentication provider for your API.
You can optionally have
Layer7 Live API Creator
store the authentication tokens that it generates for API users in a database instead by creating one.
For more information about how to create this database, see Create a Database for your Authentication Tokens.