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.

Note: The HCL DevOps Test Virtualization Control Panel (Test Virtualization Control Panel) must be running and accessible from the 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 hostname to <value>.
-e HCL_LICENSING_URL=<value> Required. The value specifies the URL of the licensing server.
Note: Licensing is limited to Concurrent Virtual Services licensing. For more information, see Licenses for DevOps Test Virtualization.
-e HCL_LICENSING_ID=<value> Required. The value specifies the id of the licensing server.
-e STUB_LICENSING_IDENTIFIER=<identifier> Optional. You can specify an licensing identifier for the stubs that you want to run in a Docker container. When you specify the identifier, you can identify licenses from the license server that are consumed by the Docker container.
You can set the licensing identifier with the following conditions:
  • Use of the characters that include A-Z, a-z, or 0-9.
    Note: All other characters, if used, are replaced by an hyphen (-).
  • The length of the identifier must not exceed 100 characters.
    Note: If the total characters exceed 100 characters, the identifier is truncated to display the first 100 characters.

At runtime, the licensing identifier that you provided is appended with a UUID for each of the stubs that you start. For example, if you set the licensing identifier as myDocker1, you can identify the licenses consumed by the stub that ran which has the UUID prefixed with the licensing identifier as in: myDocker1_f90503e5-331d-4606-bdea-a2b8e55f5c80
-e RULE_HOST=<value> Optional. If you are using Test Virtualization Control Panel and HTTP proxy the hostname that is specified as <value> is used as the hostname 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 hostname.
-e RULE_PORTS=<value> Optional. If you are using Test Virtualization Control Panel 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 Test Virtualization Control Panel. This overrides the value that is specified in the Test Integrations and APIs project file that is contained in the Docker image.
-e RULE_SECURITY_TOKEN=<value> Optional. <value> must be a valid Test Virtualization Control Panel security token. The value must be specified if domain level security is enabled in Test Virtualization Control Panel.
-e RULE_DOMAIN=<value> Optional. <value> must be the name of a valid Test Virtualization Control Panel domain. This overrides the value that is specified in the Test Integrations and APIs 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 Test Integrations and APIs 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 Test Virtualization Control Panel.

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 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 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.