Install as a Docker Container

Install as a Docker Container
lac42
You can install and configure
CA Live API Creator
to run as a Docker container. Using Docker is a convenient way to try out
CA Live API Creator
, or to run it in production. Each Docker container belongs to its own network.
For more information about how to install
CA Live API Creator
to run as a Docker container and how to configure the connection, see Docker for Databases.
The following API samples are included with Docker container installations running in non-persistent mode:
B2B Pavlov
,
B2B Northwind
,
Sample
,
Demo
,
Conference Offers
, and
Conference Management
.
No additional steps are required to load these API samples.
For more information about these API samples, see Tutorials and Samples.
In this article:
Verify the Prerequisites
Before you install
CA Live API Creator
to run as a Docker container, ensure that you have completed the following prerequisites:
  • You have installed a recent version of Docker and it is running properly.
    For more information:
    To verify your Docker version and verify if Docker is running properly, issue the following command from the command line:
    docker info
    The output gives you information about your version of Docker.
    If you get an error message, do not continue with installing and configuring
    CA Live API Creator
    to run as a Docker container.
  • You have decided which port you would like
    CA Live API Creator
    to run on. This installation assumes that the port is 8080, but you can change it to another port (the port must be greater than 1024 and less than 65535, and it is must not already be in use).
  • If you are running Docker on Windows and you want to persist the data that Docker generates and you are mapping a volume to make the license file available to the Docker container (you are using the
    --volume
    option), you have ensured that you have the appropriate permissions on your Windows machine.
    For more information about how to run Docker in persistent mode on Windows, see the Docker documentation.
  • You have reviewed the installation best practices.
    For more information about the best practices, see Installation Best Practices.
Decide How you Want to Run the Container
You can run
CA Live API Creator
as a Docker container using
one
the following deployment methods:
  • Non-persistent mode: Running
    CA Live API Creator
    as a Docker container in non-persistent mode is useful for quick demonstrations and for training. Your API definition and data changes persist until you change or remove the Docker container. If you want to preserve the changes that you make to your API, consider running in persistent mode.
  • Persistent mode: This deployment method is useful when using
    CA Live API Creator
    for an extended timeframe and you want to preserve the changes that you make to your API. When you restart the Docker container, your changes are remembered.
  • Docker Compose cluster: The Docker container for the PostgreSQL authentication token database is linked to the
    CA Live API Creator
    container that is running in persistent mode.
Run the Container in Non-Persistent Mode
You can run
CA Live API Creator
as a Docker container in non-persistent mode. This method starts a Docker container with
CA Live API Creator
installed on Apache Tomcat and using Apache Derby as its sample database.
Tomcat runs in the
/usr/local/tomcat
directory. If you are running
CA Live API Creator
as a Docker container using this deployment method, the various Derby databases are located in the
/usr/local/CALiveAPICreator/databases
directory.
Follow these steps:
  1. Start the Docker container using one of the following options:
    • If you want to access the Docker container by way of
      localhost
      and publish your host port to your Docker port, run
      CA Live API Creator
      by issuing the following command, using the
      -p
      option:
      docker
      run
      \
      -p <HOST_PORT>:<DOCKER_PORT> \
      caliveapicreator/<version>
      For more information about the options you can use with the
      docker run
      command in the Docker CLI, see the Docker CLI reference documentation.
      The
      docker run
      command does not return and shows you the output of the container. This command is helpful for diagnosing problems.
      Example:
      docker
      run
      \
      -p 8080:8080 \
      caliveapicreator/5.0.00
    • If you want to access the Docker container by way of
      localhost
      , run the container in the background and print the container ID, and publish your host port to your Docker port, run
      CA Live API Creator
      by issuing the following command, using the
      -d
      option and the
      -p
      option:
      docker
      run
      \ -d \ -p <HOST_PORT>:<DOCKER_PORT> \ caliveapicreator/<version>
      Example:
      docker
      run
      \
      -d \
      -p 8080:8080 \
      caliveapicreator/5.0.00
    You can add other options when you start the Docker container, such as avoiding the End User License Agreement screen and having to accept the End User License Agreement when you first connect to
    CA Live API Creator
    . For more information about these options, see the "Enable Other Options at Container Startup" section.
  2. Start API Creator by entering the following URL in a browser:
    http://localhost:<HOST_PORT>/APICreator
    Example:
    http://localhost:8080/APICreator
    (Mac/Linux) If you have not mapped your Docker machine IP to localhost, then use the following URL:
    http://<Docker machine IP>:8080/APICreator
  3. Log in to API Creator as the
    admin
    user.
    If the
    default
    TeamSpace is the only TeamSpace that exists, the system administrator is the initial TeamSpace user. The user name for this user is
    admin
    . Log in to API Creator as this user. If you have changed the
    admin
    user password, use that password.
You are logged in to API Creator and
CA Live API Creator
is running in non-persistent mode as a Docker container.
Run the Container in Persistent Mode
Running the Docker container in persistent mode is for when you use an admin repository that is on your local file system instead of in the Docker image. The changes that you make, such as creating an API, are not reflected in your admin repository, typically in the
teamspaces/default/apis
directory. Similarly, the changes that you make to the sample databases–such as insert, update, delete records, and change schema–are not reflected in the databases on your local file system. If you stop the Docker container and restart it later with the same mappings, your changes are saved. If the admin repository is empty,
CA Live API Creator
creates an admin repository when you start API Server.
Follow these steps:
  1. Navigate to the directory that you want to contain your Docker container in persistence mode.
  2. Access the Docker container in non-persistent mode by way of
    localhost
    by issuing the commands that run the container in the background, that print the container ID, and that publish your host port to your Docker port.
    For more information about these commands, see the "Run the Container in Non-Persistent Mode" section.
  3. Extract the sample APIs and databases that the Docker image includes to your local file system so that you can keep any changes that you make to them by issuing the following commands:
    docker ps
    docker cp <Docker container ID>:/home/tomcat/CALiveAPICreator.repository .
    docker cp <Docker container ID>:/usr/local/CALiveAPICreator/databases .
    The APIs and databases are replicated into the
    CALiveAPICreator.repository
    and
    databases
    subdirectories in the current directory. The subdirectories contain the default admin repository and the sample databases.
    The following table lists the files and directories that are most relevant in the Docker container:
    Path
    Description
    /usr/local/tomcat
    Tomcat runs in this directory, which is a standard installation including the typical subdirectories, such as
    bin
    ,
    lib
    ,
    logs
    , and
    webapps
    . It is common to map the
    server.xml
    file in this directory to a local file with different settings.
    /home/tomcat/CALiveAPICreator.repository
    The APIs are stored in this file, which is your admin repository. To persist your APIs, map this directory to your local file system.
    /usr/local/CALiveAPICreator/databases
    The Derby managed databases are stored in the
    databases/ManagedData
    subdirectory.
    If you use the built-in managed databases, then any new databases are saved in this directory. This directory also contains the various Derby databases that the Docker installation includes.
  4. Stop the Docker container by issuing the following commands:
    docker stop <Docker container ID>
    docker rm <Docker container ID>
  5. Restart the Docker container with the local repository and databases and with the volume mappings by issuing the following commands:
    docker run -p 8080:8080 \
    -v /Users/jdoe/CALiveAPICreator.repository:/home/tomcat/CALiveAPICreator.repository \
    -v /Users/jdoe/databases:/usr/local/CALiveAPICreator/databases \
    caliveapicreator/<version>
    If you do not want to have the sample APIs pre-installed, point the Docker volumes to a different directory.
  6. Start API Creator by entering the following URL in a browser:
    http://localhost:<HOST_PORT>/APICreator
    Example:
    http://localhost:8080/APICreator
    (Mac/Linux) If you have not mapped your Docker machine IP to localhost, then use the following URL:
    http://<Docker machine IP>:8080/APICreator
You are running your Docker container in persistent mode.
Run the Docker Container in a Docker Compose Cluster
You can run
CA Live API Creator
Docker container as a cluster using the Docker Compose file. The sample Docker Compose YAML file for PostgreSQL demonstrates how you can run two
CA Live API Creator
nodes with NGINX as the load balancer and use PostgreSQL as the authentication token database. To use other authentication token databases or load balancers, such as CA API Gateway, update a section of the Docker Compose file.
Prerequisites:
  • 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.
  • If you plan to have
    CA Live API Creator
    execute timers or listeners for messaging support that rely on cluster synchronization, you have configured Hazelcast for cluster synchronization strategy. Place the Hazelcast configuration XML file in the same directory as the Docker Compose file.
    You can use the Hazelcast configuration XML file as a sample for the Docker Compose file, and then modify it.
  • If you plan to persist your
    CA Live API Creator
    log messages to the
    CA Live API Creator
    instances in this cluster, you have created a logger for externalizing logging. Place this file in the same directory as the Docker Compose file.
    You can use the file as a sample logging configuration file, and then modify it.
    For more information, see External Logging.
Follow these steps:
  1. Download the sample Docker Compose YAML file for PostgreSQL. This file contains comments that explain what each line does.
  2. If you want to persist your authentication tokens, do one of the following:
    • Have the YAML file create this database as part of the Docker Compose cluster.
    • Create a database to persist your authentication tokens. This database can be a Docker container or an accessible database in the host network. Then, open the YAML file and comment out the following lines:
      database:
      image: "postgres"
      environment:
      - POSTGRES_PASSWORD=Password1
      ports:
      - "35432:5432"
      volumes:
      - "./init.apikey.sql:/docker-entrypoint-initdb.d/init.sql"
      - "apicreator_databases:/var/lib/postgresql/data"
  3. Open the YAML file, and then add the Docker volumes that you want to share.
    You can use the init.apikey.sql SQL file as a sample for the Docker Compose file. Place this file in the same directory as the Docker Compose file.
  4. If you have added nodes in the Docker Compose cluster, add them to the Hazelcast configuration XML file.
  5. Navigate to the directory that you want to contain your Docker container in a Docker Compose cluster by issuing the following command:
    $ cd <The directory containing the supporting files and the Docker Compose YAML file>
  6. Run
    CA Live API Creator
    as a Docker container in a Docker Compose cluster by issuing the following command:
    $ docker-compose up
    Example:
    $ docker-compose -f docker-compose-postgresql.yml up
  7. Enter the URL for the load balancer for the Docker Compose cluster in your browser. For example,
    localhost:8087
    .
CA Live API Creator
is running as a Docker container in a Docker Compose cluster.
Enable Other Options at Container Startup
The following are options that you can add when you start
CA Live API Creator
running as a Docker container:
For more information about these options, see API Server Startup Options.
Docker includes other options when running
CA Live API Creator
as a Docker container.
For more information about these options, see the Docker documentation.
Bypass the Extra Step at Login to Accept the EULA at Container Startup
When you first log in to API Creator, you are asked to accept the CA EULA. You can bypass this extra step when you start the Docker container by adding the following option to the Java command line:
-e ca_accept_license=ENU
Change the Password for the System Administrator User and for the Initial API Developer at Container Startup
The Docker container uses a default system administrator (
sa
) password. Specify a different password for this user by adding the following
-e
option to the Java command line when you start the Docker container:
-e LAC_INITIAL_SA_PASSWORD=<MySAPassword>
This option sets the
LAC_INITIAL_SA_PASSWORD
environment variable in the container.
Specify an Alternate License File at Container Startup
The Docker container uses a built-in default license file. You can pre-load your own license file when you start the Docker container by adding the following
-e
option to the Java command line:
-e LAC_DEFAULT_LICENSE_FILE=/licenses/MyLicense.txt
This option sets the
LAC_DEFAULT_LICENSE_FILE
environment variable in the container.
The path that you use in the command is from the perspective of the Docker container. You can map a volume to make the license file available to the Docker container by adding the following
--volume
option to the Java command line:
--volume=<host directory>:/<Docker container directory>
/
-e LAC_DEFAULT_LICENSE_FILE=/licenses/MyLicense.txt
Example:
The following example mounts the
/Users/jdoe/licensing
host directory into the
/licenses
Docker container:
--volume=/Users/jdoe/licensing:/licenses
-e LAC_DEFAULT_LICENSE_FILE=/licenses/MyLicense.txt
For more information about how to mount a host directory as a data volume, see the Docker documentation.
For more information about this option, see API Server Startup Options.
Load Libraries or Overwrite Server Configuration Files
The Docker container uses existing and expected extensions. If you are integrating
CA Live API Creator
with other services and software, you can overwrite these extensions by mounting custom configurations as host directories or files for your Tomcat server on the Docker container host. For example, you can mount a Tomcat XML configuration file (such as
context.xml
or
server.xml
) or a JAR file.
Add the following
-v
option to the command line when you start the Docker container:
-v "<Your host file or library>:<The Docker container file>
"
Examples:
The following example mounts the
server.xml
configuration file in the Docker container:
-v "conf/conf/server.xml:/usr/local/tomcat/conf/server.xml"
The following example mounts the
mylibrary.jar
library in the
{CATALINA_HOME}/lib
directory:
-v
/Users/jdoe/
mylibrary.jar:
/usr/local/tomcat/lib/
mylibrary.jar
Specify the Memory to be Used in the Docker Container
Specify the maximum amount of memory the Docker container can use by adding the following
-m
option to the command line when you start the Docker container:
-m <maximum amount of memory>
Specify a memory of at least 500M greater than the heap size.
Example:
The following example specifies a memory of 3 GB:
-m 3g
Change Heap Size for Java and Tomcat in the Container
Internally, the Docker container runs
CA Live API Creator
in Tomcat. You can change options for Java and Tomcat, such as increasing the default Java heap size, by adding the
CATALINA_OPTS
option to the Java command line when you start the Docker container, for example:
-e CATALINA_OPTS="-Xmx2048M -Djava.security.egd=file:/dev/./urandom"
The default Java heap size for Docker container installations is 256MB.
For more information about the recommended heap size for your
CA Live API Creator
installation, see Installation Requirements and Supported Platforms.
Set the Time Zone in the Container
In certain versions of the Oracle JDBC driver, you might encounter errors indicating that the time zone is not defined when you are connecting to an Oracle data source. You can specify the time zone of the Docker container by adding the following
-e
option to the Java command line when you start the Docker container:
-e TZ=<time zone>
For more information about this Oracle data source limitation, see Oracle Data Source.
Example:
The following example sets the time zone to Greenwich Mean Time (GMT):
-e TZ=GMT
Options for Integrating
CA Live API Creator
with CA API Gateway
You can enable the following options for CA API Gateway integrations.
For more information about how to integrate
CA Live API Creator
with CA API Gateway, see Integrate with CA API Gateway.
Publish More Ports at Container Startup for Integration with CA API Gateway
You can publish more ports when you start the Docker container and use them to integrate
CA Live API Creator
with CA API Gateway by adding the following
-p
option to the Java command line:
-p <HOST_PORT>:<DOCKER_PORT>
Example:
-p 8081:8081
Add Custom Host-to-IP Mapping at Container Startup for Integration with CA API Gateway
You can add custom host-to-IP mapping when you start the Docker container and use them to integrate
CA Live API Creator
with CA API Gateway by adding the following
--add-host
option to the Java command line:
--add-host=<gateway_hostname>:<gateway_hostname_IP>
Example:
--add-host=gw92.ca.com:34.203.50.194
Configure Tomcat Server for Mutual Authentication at Container Startup for Integration with CA API Gateway
You can configure Tomcat server for mutual authentication for integrating
CA Live API Creator
with CA API Gateway when you start the Docker container by mounting Tomcat configuration files (such as
context.xml
or
server.xml
).
You can download the following sample configuration files as your baseline configuration files:
If you use these files, open them and uncomment the
GATEWAY
section of the code.
Add the following
-v
option to the Java command line:
-v <Your host file or library>:<The Docker container file>
Example:
The following example mounts the
server.xml
configuration file in the Docker container:
-v /Users/jdoe/lac/server.xml:/usr/local/tomcat/conf/server.xml
Connect to
CA Live API Creator
Running as a Docker Container
Enter the following URL into a browser window:
http://localhost:8080/APICreator
By default, the developer username is
admin
and the password is
Password1
.
You are connected to the running Docker container.
Create your Own Docker Container
You can create your own version of the Docker container that is based on the standard container. A custom Docker container is useful, for example, if you want to add JDBC drivers, without having to map files or directories. The base Docker image for
CA Live API Creator
is based on the standard Tomcat image (
tomcat:9.0.8-jre9-slim
for the 5.0.00 release), which itself is based on the standard OpenJDK image, which is based on Debian. This means that you can use the APT package manager to install software.
Follow these steps:
  1. Copy any files that you want to add or modify in the standard Docker image, such as a customized
    server.xml
    configuration file for Tomcat, or a JDBC driver JAR file, to the current directory.
    The Docker container includes Tomcat to run
    CA Live API Creator
    . The Ghostcat vulnerability (CVE-2020-1938) is a vulnerability found in Apache Tomcat's AJP Connector that listens on port 8009. Tomcat treats AJP connections with more trust than connections such as HTTP. AJP connections allow attackers to exploit them to perform actions that are not intended for an untrusted user.
    The default
    CA Live API Creator
    Docker container does not open port 8009. With your own Docker container, avoid the Ghostcat vulnerability by not exposing this port.
    For more information about this vulnerability, see CVE-2020-1938 on the Common Vulnerabilities and Exposures (CVE) site.
  2. Create a Docker file that includes these files and installs any other package, for example:
    FROM caliveapicreator/5.0.00
    MAINTAINER Your name here
    COPY server.xml /usr/local/tomcat/conf/
    COPY ojdbc8.jar /usr/local/tomcat/lib/
    RUN apt-get install libmongodb-java
  3. Create your Docker image by issuing the following command:
    docker
    build
    -t my_lac_docker
    Output similar to the following is expected:
    Sending build context to Docker daemon 4.387MB
    Step 1/4 : FROM caliveapicreator/5.0.00
    ---> 5c4deff6db45
    Step 2/4 : MAINTAINER Your name here
    ---> Using cache
    ---> fcf84e18777e
    Step 3/4 : COPY server.xml /usr/local/tomcat/conf/
    ---> Using cache
    ---> 8f3594a7e645
    Step 4/4 : COPY ojdbc8.jar /usr/local/tomcat/lib/
    ---> 6bf37ad7dd81
    Successfully built 6bf37ad7dd81
    Successfully tagged my_lac_docker:latest
  4. Run the Docker image by issuing the following command:
    docker
    run
    -p 8080:8080 my_lac_docker
  5. Verify that API Creator is running by entering the following URL in a browser:
    http://localhost:8080/APICreator
You have created your own custom Docker container.
Examine the Docker Container
Prerequisite:
The Docker container is running.
Follow these steps:
  1. List your containers by issuing the following command:
    docker
    ps
    A result similar to the following is expected:
    CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
    9376d7985de1
    caliveapicreator/5.0.00 "catalina.sh run" 5 minutes ago Up 4 minutes 8080/tcp lac
  2. Copy the Docker container ID.
  3. Start a shell in the container by issuing the following command:
    docker
    exec
    -it 9376d7985de1 bash
    A command prompt appears.
You can now browse the file system.
Stop or Remove your Docker Container
  1. List the Docker containers by issuing the following command:
    $ docker
    ps
    -a
    A result similar to the following is expected:
    CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS
    547911c7c2cc caliveapicreator/5.0.00 "StartLiveAPICreator." 7 minutes ago Up 7 minutes 0.0.0.0:8080->8080/tcp
  2. Complete one of the following options:
    • To stop the Docker container, issue the following command:
      $ docker
      stop
      <Docker container ID>
    • To remove the Docker container, issue the following command:
      $ docker
      rm
      <Docker container ID>
The Docker container is stopped or removed.
Remove the Docker Image
  1. List the Docker images by issuing the following command:
    $ docker
    images
    A response similar to the following is expected:
    REPOSITORY TAG IMAGE ID CREATED SIZE
    caliveapicreator/5.0.00 latest 96b2a3d11452 2 days ago 580.4 MB
  2. Remove the image by issuing the following command:
    $ docker
    rmi
    <Docker image ID>
The Docker image is removed.