Running stubs in a Docker container

After you publish one or more stubs to a Dockerfile and build context and you built a Docker image from those files, you use the docker run command to run the image in a container.
The basic syntax for running a Docker image is as follows:
docker run Options <image name>

The following table lists some docker run options that you can use with the docker run command when you run an image that contains published stubs. For more information about all of the general docker run options, see the Docker Documentation.

Options Description
-p <external_host_port>:<container_host_port> Explicitly maps a port on the host to an exposed container port. For more information about mapping ports, see the Docker Run Reference.
-P Maps the exposed container ports to the host. Each exposed port is mapped to an ephemeral port on the host. When the container is running, you can see how the ports were mapped by using the docker port command. For more information about mapping ports, see the Docker Run Reference.
-d Runs the container in detached mode
-h <value> Overrides or sets the container host name to <value>.
-e RATIONAL_LICENSE_FILE=<value> Required if you run a container that is published from the full edition of HCL OneTest™ API to obtain an appropriate license. <value> is the host and port of the Rational Common Licensing server in the format port@fully_qualified_host. If HCL Quality Server is using the default port of 27000 the port can be excluded. The license server must be both accessible and have available licenses when the container starts.
-e RULE_HOST=<value> Optional. If you are using HCL Quality Server and HTTP proxy the host name that is specified as <value> is used as the host name in routing rules that are sent to the proxy. This causes the proxy to send requests to one or more stubs by using the specified host name.
-e RULE_PORTS=<value> Optional. If you are using HCL Quality Server and HTTP proxy this environment variable allows the values of ports that are used within the container to be correctly reflected in routing rules, if the container port is mapped to a different port on the host. <value> must be a comma-separated list of port mappings of the following form:
<external_port>:<container_port>
Note: RULE_HOST and RULE_PORTS assume that you know this information when the container is run. If for example you use the -P option you might not know the port mappings as the automatic mapping by Docker uses free ephemeral ports. Instead of using RULE_HOST and RULE_PORTS, you can use the RULE_ENDPOINT_FILE environment variable.
-e RULE_ENDPOINT_FILE=<value> Optional. <value> is the name of a file within the container that is processed to get the host and port mapping information. While the specified file does not exist, the run time waits and does not start the stubs. This allows for host and port information to be provided after calling docker run. The lines in the file must be one or more of:
hostname=<hostname>
<external_port>:<container_port>
<container_port> -> <external_port> (This syntax is the format from the docker port command)

You can pass a rule file into a running container by using docker cp.
-e RULE_SERVER=<value> Optional. <value> must be the URL for HCL Quality Server. This overrides the value that is specified in the HCL OneTest™ API project file that is contained in the Docker image.
-e RULE_SECURITY_TOKEN=<value> Optional. <value> must be a valid HCL Quality Server security token. The value must be specified if domain level security is enabled in HCL Quality Server.
-e RULE_DOMAIN=<value> Optional. <value> must be the name of a valid HCL Quality Server domain. This overrides the value that is specified in the HCL OneTest™ API project file that is contained in the Docker image.
-e RUNTESTS_LOG_LEVEL=<value> Optional. <value> can be DEBUG, INFO, WARNING, or ERROR. If set, the HCL OneTest™ API related classes log at the specified level. If not specified, WARNING is used.
Note: If none of RULE_HOST, RULE_PORTS or RULE_ENDPOINT_FILE are specified, routing rules are not sent to HCL Quality Server.

Example 1

This is an example for a stub that is listening (exposed) on port 8081 in the container and explicitly mapped to port 1234 on the host mydockerhost.local:

docker run -d -p 1234:8081 -e RULE_HOST=mydockerhost.local -e RULE_PORTS=1234:8081 -e RATIONAL_LICENSE_FILE=@licenseserver.local stubimage

Example 2

This is an example for a stub that is listening (exposed) on port 8082 in the container and automatically mapped to an ephemeral port on the host mydockerhost.local:

docker run -d -P -e RULE_ENDPOINT_FILE=/endpoint.txt -e RATIONAL_LICENSE_FILE=@licenseserver.local stubimage
Once executed, a file that is named endpoint.txt can be created on the Docker host at /tmp/endpoint.txt. Assuming port 8082 was mapped to 37001 on the host (the docker port command can be used to see the port mappings), the file can contain:
hostname=mydockerhost.local
37001:8082
which can be copied into the container by using this Docker command:
docker cp /tmp/endpoint.txt <container_id>:/endpoint.txt
where <container_id> is identified for the running container.