Install as a Docker Container

Install as a Docker Container
lac52
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.
In this article:
3
Verify the Prerequisites
Before you install
CA Live API Creator
to run as a Docker container, ensure that you have completed the following prerequisite steps:
  • You have installed a recent version of Docker and it is running properly (you are not getting error messages).
    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.
    Important!
    If you get an error message, do not continue with installing and configuring
    CA Live API Creator
    to run as a Docker container.
  • You know which license type you are using
    CA Live API Creator
    under, either a standard microservice license that the CA Support site issues or an Enterprise Software Portfolio License Agreement (PLA).
    For more information about licensing, see Licensing.
  • 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.
Configure the Container to Collect and Send Usage Data
If you are running
CA Live API Creator
as a Docker container licensed under a PLA, you must activate
CA Live API Creator
and configure it to collect and send usage data. If you are licensed to run
CA Live API Creator
as a Docker container licensed under a standard microservice license, you can consent to
CA Live API Creator
collecting and sending usage data.
You can configure the Docker container to collect and send usage data using the following methods:
  • (Recommended) By changing the
    system/telemetry.json
    file that is part of your admin repository. This file contains the usage data configurations. To use this method, run the Docker container in persistent mode with the volume mappings.
    For more information about how to run the Docker container in persistent mode with the volume mappings, see the "Run the Container in Persistent Mode" section.
  • By adding the telemetry startup options when you start API Server.
    For more information about these options, see API Server Startup Options.
  • By activating
    CA Live API Creator
    and configuring it to send usage data during the installation and activation process using API Creator after the Docker container is running.
    For more information about this method, see Activate and Configure to Send Usage Data.
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.
    CA Live API Creator
    persists your API definition and data changes 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.
    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.
  • 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: Link the Docker container for the authentication token database 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.2.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.2.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 log in to API Creator.
      For more information about these options, see the "Enable Other Options at Container Startup" section.
  2. Enter 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
    The API Creator logon authentication dialog opens.
  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 you are running
CA Live API Creator
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. If you are running Docker in non-persistent mode and you want the changes to be in the Docker container running in persistent mode, complete the following:
    1. 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.
    2. 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
      cd /Users/jdoe # Or any directory on your local file system
      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
      Your 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.
    3. Stop and remove the Docker container by issuing the following commands:
      docker
      stop
      <Docker container ID>
      docker
      rm
      <Docker container ID>
  3. Start (or 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>
  4. 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 (
docker-compose-example.yml
) demonstrates running two
CA Live API Creator
nodes with NGINX as the load balancer and uses PostgreSQL as the authentication token database. This file contains comments that explain what each line does. You can update this sample file to use other authentication token databases or load balancers, such as CA API Gateway.
Prerequisites:
  • You have created 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 configuration XML file as a sample for the Docker Compose file, and then modify it.
    For more information, see Configure to Run as a Cluster.
  • 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 YAML file.
  2. If you want to persist your authentication tokens, create a database for your authentication tokens. This database can be a Docker container or an accessible database that
    CA Live API Creator
    supports. You can have the YAML file create this database as part of the Docker Compose cluster or you can create this database.
    For more information about the how to create this database, see Create a Database for your Authentication Tokens.
  3. Open the YAML file, add the following, and then save and close the file:
    • The Docker volumes that you want to share.
      You can use the SQL file as a sample for the Docker Compose file. Place this file in the same directory as the Docker Compose file.
    • If you have created a database for persisting your authentication tokens (instead of having the YAML file create it), 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"
  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. Download the sample load balancer configuration file (the file) and copy it to the same directory as the Docker Compose file. This file includes the configuration for the NGINX load balancer that
    CA Live API Creator
    spins up when you run the sample Docker Compose YAML file for PostgreSQL (
    docker-compose-example.yml
    ).
  7. 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
  8. 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 the password for the initial API developer (a TeamSpace user) for the
default
TeamSpace by adding the following
-e
option to the Java command line when you start the Docker container:
-e LAC_INITIAL_ADMIN_PASSWORD=<MyAdminPassword>
Specify an Alternate License File at Container Startup
The Docker container uses a built-in default license file. If you are licensed to use
CA Live API Creator
under a standard microservice license, 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.
Configure to Collect and Send Usage Data at Container Startup
You can configure
CA Live API Creator
to collect and send usage data when you start your Docker container by adding the telemetry options. If you are licensed to use
CA Live API Creator
under a PLA, you must configure it to collect and send usage data.
For more information about these options, see API Server Startup Options.
Load Libraries or Overwrite Server Configuration Files at Container Startup
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 at Container Startup
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 at Container Startup
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 512MB.
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 at Container Startup
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
Log in to API Creator
Enter the following URL into a web browser window:
http://localhost:<HOST_PORT>/APICreator
Example:
http://localhost:8080/APICreator
By default, the developer username is
admin
and the password is
Password1
.
You are logged in to API Creator.
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 (
9.0.12-jre8-slim
for
CA Live API Creator
5.1), which itself is based on the standard OpenJDK image, which is based on the Debian operating system.
You can install software using Advanced Package Tool (APT).
For more information about Debian and APT, see the Debian website.
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.2.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.2.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
  1. With the Docker container running, list your Docker 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.2.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 Docker container by issuing the following command:
    docker
    exec
    -it <Docker container ID> bash
    A command prompt appears.
You can now browse the file system.
Stop or Remove your Docker Container
  1. With the Docker container running, 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.2.00 "StartLiveAPICreator." 7 minutes ago Up 7 minutes 0.0.0.0:8080->8080/tcp
  2. Copy the Docker container ID.
  3. 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. With the Docker container running, 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.2.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.