Install on Apache Tomcat

Install on Apache Tomcat
lac52
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 you install 
CA 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 
    CA 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 
    CA 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 
CA 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 
CA 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 
CA 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 
CA 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 
CA Live API Creator
-specific usage data.
You can also activate 
CA 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 
CA Live API Creator
 Components Simultaneously
Follow these steps:
  1. Retrieve the 
    development/CALiveAPICreator.war
     file from your 
    CA Live API Creator
     installation bundle and copy it to the 
    ${CATALINA_HOME}/webapps
     directory.
  2. (If you want 
    CA Live API Creator
     to be at the root URL) Rename the 
    CALiveAPICreator.war
     file to 
    ${CATALINA_HOME}/webapps/ROOT.war
    .
Install an Individual 
CA 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 
    CA 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 
CA 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 
CA Live API Creator
 supports, see Installation Requirements and Supported Platforms.
Follow these steps:
 
  1. Copy the 
    <
    CA 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 
CA 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 
CA Live API Creator
 to Access URLs that Contain Special Characters
You can configure 
CA 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 
    CA 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 
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>
    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 
CA Live API Creator
 applications at the Java-container level.
Next Steps
Complete the following procedures after you have installed 
CA 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 
CA Live API Creator
 under a standard license, the first time that you start Tomcat with 
CA 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 
CA Live API Creator
 to Pull your Admin Repository
By default, at initial server startup, 
CA 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 
CA Live API Creator
 to Add your Admin Repository
The first time that you start Tomcat with 
CA 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 
        CA Live API Creator
         under a standard license and this is the first time that you start Tomcat with 
        CA Live API Creator
        , you must install your license for 
        CA 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 
CA Live API Creator
 is installed.
Log in to API Creator
You can access the 
CA 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 
    CA Live API Creator
     creates when you install 
    CA 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 
CA Live API Creator
 to Collect and Send Usage Data
If you are licensed to use 
CA Live API Creator
 under a PLA, you must activate 
CA Live API Creator
 and configure it to collect and send usage data. If you are licensed to use 
CA Live API Creator
 under a standard license, you can consent to 
CA 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 
CA 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 
CA 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 
CA 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 
CA 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 
CA Live API Creator
 to run as a cluster, see Configure to Run as a Cluster.
Create a Database for your Authentication Tokens
By default, 
CA 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 
    CA 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 
CA 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.