Install as a Docker Container

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.
lac40
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.
In this article:
Verify the Prerequisites
Ensure that you have completed the following prerequisites before you install 
CA Live API Creator
 to run as a Docker container:
  • You have installed a recent version of Docker (1.11 or newer on Linux or 1.12.3 or later on Mac/Windows) and it is running properly.
    For more information about how to install and running Docker (Mac), see the Docker documentation.
    To verify your Docker version and verify if Docker is running properly, run 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 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 is not already in use).
Decide How you Want to Run the Container
You can run 
CA Live API Creator
 as a Docker container using the following deployment methods:
  • Non-persistent mode (one-minute version). 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 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 you make to your API. When you restart the Docker container, your changes are remembered.
  • Persistent mode using MySQL as your admin database. Running 
    CA Live API Creator
     as a Docker container in MySQL mode typically is the mode that is used for production. You can use this deployment method in a cluster. The Docker container stores its information in a MySQL database, without any samples pre-installed.
  • Docker Compose cluster. The Docker container for the MySQL admin database is linked to the 
    CA Live API Creator
     Docker container, 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 Derby configured as the admin database and as its sample databases.
  • Derby as an admin database is supported only for demonstration and proof of concept (POC) purposes. Using Derby as your admin database limits your ability to upgrade to the next 
    CA Live API Creator
     release.
  • 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 
CA Live API Creator
 is installed on Tomcat and is running as a Docker container in non-persistent mode or persistent mode and you have configured Derby as the admin database, the various Derby databases are in the
/usr/local/CALiveAPICreator/databases
 directory.
Follow these steps:
  1. Start the Docker container with 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.0.01
    • 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.0.01
    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 with user name 
    admin
     and password 
    Password1
    .
     If you already have 
    CA Live API Creator
     installed, and you have changed your password, use your 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
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.
  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 /home/docker/LiveAPICreator:/usr/local/CALiveAPICreator \
    caliveapicreator/4.0.01
    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 the admin database directory is empty, the following message appears:
    Databases not found -- initializing with default
    This message indicates that the repository was not found, and therefore a default repository was created, pre-loaded with two sample APIs. If you delete the 
    CA Live API Creator
     Docker image, this directory is not deleted 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 MySQL as Your Admin Database
When you run 
CA Live API Creator
 as a Docker container using this mode, 
CA Live API Creator
 uses a MySQL database as the admin database. You can provide your own MySQL database or you can use a pre-configured Docker container.
In this configuration, sample APIs are not created. You can change these options to use a pre-existing MySQL installation instead of a Docker container.
The directory you use to store the MySQL data must exist in your Docker Machine, must be writable, and the underlying disk must have enough free space. MySQL 5.6 should work, but MySQL 5.6.29 is known to work. If you want to publish your container port to your localhost, ensure that you select a port that is not used in your localhost.
For more information about the MySQL data source versions that 
CA Live API Creator
 supports, see Installation Requirements and Supported Platforms.
Follow these steps:
  1. If you do not already have a MySQL server that you want to use, start the MySQL Docker container by issuing the following command, using the 
    --volume
     option to add a volume to persist the data:
    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=/home/docker/lacadmin:/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 by issuing the following command, passing in the MySQL database information as environment variables from an existing MySQL admin database or MySQL Docker container:
    docker
    run
    \
    -e RDS_HOSTNAME=<the MySQL hostname> \
    -e RDS_PORT=<the MySQL port> \
    -e RDS_USERNAME=<the MySQL username> \
    -e RDS_PASSWORD=<the MySQL password> \
    -e RDS_DB_NAME=<the MySQL 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 MySQL mode, 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.0.01
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 for the 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 that 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 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 the 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 website.
 You can use the following commands to navigate Docker volumes:
## 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 additional 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:
--volume=/Users/jdoe/licensing:/licenses
-e LAC_DEFAULT_LICENSE_FILE=/licenses/MyLicense.txt
The 
-v
 option mounts the host directory, 
/Users/jdoe/licensing
, into the container at 
/licenses
.
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 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 
mylibrary.jar
 library in the 
{CATALINA_HOME}/lib
 directory:
-v
/Users/jdoe/
mylibrary.jar:
/usr/local/tomcat/lib/
mylibrary.jar
Options for Integrating 
CA Live API Creator
 with CA API Gateway
You can enable the following options for CA API Gateway integrations.
Publish Additional Ports at Container Startup for Integration with CA API Gateway
You can publish additional ports used for integrating 
CA Live API Creator
 with CA API Gateway when you start the Docker container by specifying the following option on the command line: 
-p <HOST_PORT>:<DOCKER_PORT>
 
Example:
 
-p 8081:8081
For more information about how to integrate 
CA Live API Creator
 with CA API Gateway, see Integrate with CA API Gateway.
Add Custom Host-to-IP Mapping at Container Startup for Integration with CA API Gateway  
You can add custom host-to-IP mapping for integrating 
CA Live API Creator
 with CA API Gateway when you start the Docker container 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
For more information about how to integrate 
CA Live API Creator
 with CA API Gateway, see Integrate with CA API Gateway.
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.
For more information about how to integrate 
CA Live API Creator
 with CA API Gateway, see Integrate with CA API Gateway.
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 user name is 
admin
 and the password is 
Password1
.
You are connected to the running Docker container.
Examine the Docker Container
Prerequisite:
 The Docker container is running.
 You can examine the Docker container.
  1. List your containers by issuing the following command:
    docker
    ps
    A result similar to the following is expected:                           
    CONTAINER ID
    IMAGE
    COMMAND
    CREATED
     
    9376d7985de1
     
    caliveapicreator/4.0.01
    "catalina.sh run"
    4 minutes ago
  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.
Stop or Remove your Docker Container
To stop your Docker containers, complete the following:
  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.0.01
    "StartLiveAPICreator."
    7 minutes ago
    Up 7 minutes
    0.0.0.0:8080->8080/tcp
  2. Execute the following:
    • Stop the Docker container by issuing the following command:
      $ docker
      stop
      <Docker container ID>
    • Remove the Docker container by issuing the following command:
      $ docker
      rm
      <Docker container ID>
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.0.01
    latest
    96b2a3d11452
    2 days ago
    580.4 MB
    mysql
    5.6.29
    cf859bd8ff7f
    3 weeks ago
    324.2 MB
  2. Remove the image by issuing the following command:
    $ docker
    rmi
    <Docker image ID>