Install as a Docker Container

Install as a Docker Container
calac41
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 or, when running as a Docker Compose cluster, to a shared subnetwork.
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 that use Apache Derby as the admin database: 
B2B Pavlov
B2B Northwind
Sample
Demo
Marketing
, and 
Marketing - Accounting
.
No additional steps are required to load these API samples.
For more information about these API samples, see API 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.
    Warning!
    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 API Creator to run on. This installation assumes that the port is 8080, but you can change it to any port (as long as it is greater than 1024, less than 65535, and it is not already in use).
  • If you are running Docker on Windows and you want to persist the data that Docker generates and uses 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 the following deployment methods:
Run the Container in Non-Persistent Mode Using Derby as Your Admin Database
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 Derby as your admin database and as its sample databases.
  • CA Live API Creator
     supports Derby as an admin database only for demonstration and proof of concept (POC) purposes. 
    CA Live API Creator
     does not upgrade Derby admin databases automatically when you upgrade 
    CA Live API Creator
     from a previous version.
    For more information about how to upgrade 
    CA Live API Creator
     if you have configured Derby as your admin database, see Upgrade CA Live API Creator.
  • Limitations: 
     
    CA Live API Creator
     supports Derby only in embedded mode. In this mode, Apache Derby does not support cluster configurations. Only one server can access the database at any given time.
Tomcat runs in the 
/usr/local/tomcat
 directory. If you are running 
CA Live API Creator
 as a Docker container using the non-persistent mode 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/4.1.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/4.1.00
    You can enable other options when starting 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 Using Derby as Your Admin Database 
The Docker container stores its information about the host's file system. Decide where you want the Docker container to store its information. The storage is in your Docker virtual machine, but you can share a directory between the host machine and the Docker Machine by mounting a volume.
For more information about the Docker Machine, see the Docker documentation.
This deployment method also persists the default Derby managed databases. These databases are located in the 
<host directory>/databases/ManagedData
 directory.
CA Live API Creator
 supports Derby as an admin database only for demonstration and POC purposes. 
CA Live API Creator
 does not upgrade Derby admin databases automatically when you upgrade 
CA Live API Creator
 from a previous version.
For more information about how to upgrade 
CA Live API Creator
 if you have configured Derby as your admin database, see Upgrade CA Live API Creator.
Follow these steps:
 
  1. If you want to access the Docker container by way of 
    localhost
    , start the Docker container by issuing the following command, using the 
    -p
     option to publish your container port to your localhost and using the 
    -v
     option to specify the directory for persistent storage:
    docker
    run
    -p <HOST_PORT>:<DOCKER_PORT> \
    -v <host directory>:<Docker container directory> \
    caliveapicreator/<version>
    Example:
     
    docker
    run
    -p 8080:8080 \
    -v /Users/jdoe/Documents/DockerPersist:/usr/local/CALiveAPICreator \
    caliveapicreator/4.1.00
    You can enable other options when starting 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.
    When you run the container in persistent mode and share a directory between the host machine and the Docker Machine, you use the 
    /usr/local/CALiveAPICreator
     default Docker container directory. If your admin database directory is empty, the following message appears:
    Databases not found -- initializing with default
    This message indicates that the container did not find the repository, and therefore, it created a default repository. If you delete the 
    CA Live API Creator
     Docker image, the container does not delete the repository from the Docker Machine.
  2. Start API Creator by entering the following URL in a browser:
    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
Run the Container in Persistent Mode Using a Relational Database as Your Admin Database
When you run 
CA Live API Creator
 as a Docker container using this mode, 
CA Live API Creator
 uses a relational database as the admin database. You can provide your own database or you can use a pre-configured Docker container. You can also use a pre-existing database installation instead of a Docker container.
This deployment method does not include sample APIs.
The directory that you use to store the relational data must exist in your Docker Machine, must be writable, and the underlying disk must have enough free space. If you want to publish your container port to your localhost, ensure that you select a port that is not used in your localhost.
Follow these steps:
  1. If you do not already have a relational database server that you want to use, start its Docker container by issuing the following command, using the 
    --volume
     option to add a volume to persist the data:
    This example uses MySQL as the Docker container. Use the options based on the relational database that you are using as your Docker container type.
    docker
    run
    \
    -e MYSQL_ROOT_PASSWORD=<your MySQL root password> \
    -e MYSQL_DATABASE=<your MySQL database name> \
    -e MYSQL_USER=<your MySQL username> \
    -e MYSQL_PASSWORD=<your MySQL password> \
    --volume=<host directory where you store the MySQL data on your Docker Machine>:<Docker container directory> \
    -p <HOST_PORT>:<DOCKER_PORT> \
    mysql:<MySQL version>
    Example:
     
    docker
    run
    \
    -e MYSQL_ROOT_PASSWORD=Password1 \
    -e MYSQL_DATABASE=lacadmindb \
    -e MYSQL_USER=lacadminuser \
    -e MYSQL_PASSWORD=Password2 \
    --volume=/Users/jdoe/Documents/DockerPersist:/var/lib/mysql \
    -p 3306:3306 \
    mysql:5.6.29
    The MySQL Docker container is up and running. The MySQL Docker container can 10-20 seconds to start up after the container is downloaded.
  2. Start 
    CA Live API Creator
     as a Docker container using one of the following methods:
    • By issuing the following command, passing in the relational database information as environment variables from an existing relational admin database or relational database Docker container:
      docker
      run
      \
      -e RDS_HOSTNAME=<the database server hostname> \
      -e RDS_PORT=<the database server port> \
      -e RDS_USERNAME=<the database server username> \
      -e RDS_PASSWORD=<the database server password> \
      -e RDS_DB_NAME=<the database name> \
      -e LAC_ADMIN_MAX_CONN=200 \
      -p <HOST_PORT>:<DOCKER_PORT> \
      caliveapicreator/<CA Live API Creator version>
      You can enable other options when starting the Docker container in persistent mode using a relational database as your admin database, 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.
      Example:
      docker
      run
      \
      -e RDS_HOSTNAME=127.0.0.1 \
      -e RDS_PORT=3306 \
      -e RDS_USERNAME=lacadminuser \
      -e RDS_PASSWORD=Password2 \
      -e RDS_DB_NAME=lacadmindb \
      -e LAC_ADMIN_MAX_CONN=200 \
      -p 8080:8080 \
      caliveapicreator/4.1.00
    • By passing in your JDBC information using the following environmental variables. This method provides you flexibility to specify extra options within the JDBC URL.
      docker
      run
      \
      -e JDBC_CONNECTION_STRING=<the raw JDBC URL> \
      -e JDBC_CONNECTION_USERNAME=<the database username> \
      -e JDBC_CONNECTION_PASSWORD=<the database password> \
      -e JDBC_CONNECTION_DB_NAME=<the database name> \
      -e LAC_ADMIN_MAX_CONN=100 \
      -p <HOST_PORT>:<DOCKER_PORT> \
      caliveapicreator/<CA Live API Creator version>
The Docker container can take a few seconds to start up.
Run the Container in a Docker Compose Cluster
You can run 
CA Live API Creator
 in a Docker Compose cluster using a MySQL (or PostgreSQL) Docker container as your admin database. The YAML file contains a description of the following sections:
  • A MySQL (or PostgreSQL) Docker container for 
    CA Live API Creator
    's admin database. 
  • CA Live API Creator
     Docker container.
Follow these steps:
 
  1. Download the Docker Compose YAML file that pertains to the Docker container you want to use as your admin database:
  2. Edit the Docker Compose YAML file to change the version of MySQL (or PostgreSQL), the database password, the ports that are exposed, and/or the version of 
    CA Live API Creator
    .
  3. Save and close the Docker Compose YAML file.
  4. Start 
    CA Live API Creator
     as a Docker container in a Docker Compose cluster by issuing the following command:
    $ docker-compose -f <the Docker Compose file for the (MySQL or PostgreSQL) admin database> up
    Example:
     
    $ docker-compose -f docker-compose-mysql.yml up
The Docker container for the (MySQL or PostgreSQL) admin database is linked to the 
CA Live API Creator
 Docker container.
 
CA Live API Creator
 is running in a Docker Compose cluster.
We recommend that you persist data for your admin database services using the volumes that are commented in their respective Docker Compose files. You can describe configuration volumes for each specific service, but some Docker Containerized database directories, such as SQL Server-Linux, do no support mounting directly to the host.
For more information about how to manage the volumes that are commented in their respective Docker Compose files, see the Docker documentation . 
 You can navigate Docker volumes using the following commands:
## list your local volumes
$ docker volume ls
## show specific details about a specific volume
$ docker volume inspect {{volume_name}}
Enable Other Options at Container Startup
You can enable the following options when you run 
CA Live API Creator
 as a Docker container:
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 specifying the following option on the command line:
-e ca_accept_license=ENU
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 specifying the following 
-e
 option on the 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 using the following options:
--volume=<host directory>:/<Docker container directory>
/
-e LAC_DEFAULT_LICENSE_FILE=/licenses/MyLicense.txt
Example:
 
The following code block shows how to mount the 
/Users/jdoe/licensing
 host directory into the 
/licenses 
Docker container using the 
-v
 option:
--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.
Adjust the Timeout Period for the Port and Host to be Open at Container Startup
If you specified a value for the 
RDS_HOSTNAME
 and the 
RDS_PORT
 variables when you started 
CA Live API Creator
 as a Docker container in the command line, then the Docker instance waits for the port on that host to be open before it starts Tomcat. Having the Docker instance wait for the port to be open before it starts Tomcat is useful when you start 
CA Live API Creator
 and a database server simultaneously, like in a Docker Compose file.
By default, the Docker instance waits for up to 60 seconds for that port on that host to become open. If you need that timeout to be longer (or shorter), typically because you anticipate that the database server may take a long time to start, you can adjust the timeout period when you start the Docker container by specifying the following options on the command line:
-e RDS_HOSTNAME=dbserver /
-e RDS_PORT=3306 /
-e LAC_START_DB_TIMEOUT=300
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 files (such as 
context.xml
 or 
server.xml
) or a JAR file.
 Specify the following options to the command line:
-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
Change Heap Size for Java and Tomcat in the Container
Internally, the Docker container runs 
CA Live API Creator
 in Tomcat. You can specify additional options to Java and Tomcat, such as increasing the default Java heap size, by setting the 
CATALINA_OPTS
 environment variable, for example:
-e CATALINA_OPTS='-Xmx512M'
The default Java heap size is 256MB. We recommend a minimum of 512MB of heap and a maximum of 2GB.
For more information about the best practices for configuring your heap size, see Configuration Best Practices.
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 specifying the following option on the 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 specifying the following option on the 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.
Specify the following options to the 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 "conf/conf/server.xml:/usr/local/tomcat/conf/server.xml
Start 
CA Live API Creator
 Running In 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 based on the standard container. This is useful if you want to add JDBC drivers, or customize the container, without having to map files or directories.
Follow these steps:
 
  1. Copy to the current directory 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.
  2. Do 
    one
     of the following:
    • Customize the 
      server.xml
       file to include a JNDI data source.
    • Change the configuration parameters for Tomcat.
    You can make these same customizations with any file in the Docker image.
  3. Create a Docker file that includes these files. For example, the following Docker file includes the 
    server.xml
     configuration file and the 
    ojdbc8.jar
     files:
    FROM caliveapicreator/4.1.00
    MAINTAINER Your name here
    COPY server.xml /usr/local/conf/
    COPY ojdbc8.jar /usr/local/tomcat/lib/
  4. Create your Docker image with by issuing the following command:
    docker
    build
    -t my_lac_docker .
    Example output:
    Sending build context to Docker daemon 4.387MB
    Step 1/4 : FROM caliveapicreator/4.1.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
  5. Run the Docker image by issuing the following command:
    docker
    run
    -p 8080:8080 my_lac_docker
  6. 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/4.1.00 "catalina.sh run" 4 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 <Docker container ID> 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
    ac7660d368e5 mysql:5.6.29 "/entrypoint.sh mysql" 31 seconds ago Up 30 seconds 3306/tcp
    547911c7c2cc caliveapicreator/4.1.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 
CA Live API Creator
 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/4.1 latest 96b2a3d114522 days ago580.4 MB
    mysql5.6.29cf859bd8ff7f3 weeks ago324.2 MB
  2. Remove the image by issuing the following command:
    $ docker
    rmi
    <Docker image ID>
The Docker image is removed.