Public Repository

Last pushed: 2 months ago
Short Description
Docker Image containing released builds of ReadyAPI VirtServer
Full Description

Docker Image containing latest build of ReadyAPI VirtServer

Running VirtServer as a Docker Image

When doing docker run (or equivalent in Docker Cloud or similar) you pass information between the outside world
and the docker image by setting up environment variables. In Docker Cloud or similar solutions these variables are typically setup in a table view but when running from a command-line they are passed as arguments following the docker run command.

docker run -e EnvironmentVariable1Name=EnvironmentVariable1Value -e EnvironmentVariable2Name=EnvironmentVariable2Value smartbear/ready-api-virtserver

When running the docker image through "docker run" it is also possible to use the --env-file argument to specify a file with all the environment settings. Read more about that in the docker manual.

Environment Variable Optional Description
VirtServerUser Yes* A user name to be added to the user database as a VirtServer admin user
VirtServerPassword Yes* The password of the VirtServerUser added above
VirtServerLicenseServer No hostname:port of the floating license server, if missing the server will expect a trial license to be passed in using VirtServerLicense
VirtServerClassPathExt Yes Specify the location of the ext directory for adding additional jars
DockerUser Yes A user to be used instead of root when requesting a license from the floating license server, if not set the user will be root
UseHTTPS Yes Use HTTPS for the communication with VirtServer. The default value is true (recommended)
CertificateSubject Yes A subject string to use when generating a self signed password. A correct subject string typically looks something like this:<br>/C=US/ST=MA/L=Somerville/O=SmartBear/OU=com/CN=virtserver.smartbear.local
CONFIG Yes Optional image relative path to an alternative configuration file
JVM_OPT_<unique_id> Yes Additional JVM options can be passed in by adding environment variables with the option name JVM_OPT_<unique_id>. Use the format JVM_OPT_1=-Dproperty=value (see more below)
USAGE_STATISTICS Yes Send usage statistics (defaults to true)
ACCEPT_TOU Yes* Before running VirtServer you must accept the Terms of Use ( You state that you are doing so by passing in ACCEPT_TOU=true to the docker container. If the container is using a mapped volume, the VirtServer will remember that the Terms of Use has been accepted and the environment variable becomes optional for future runs.

*) Usually required once, if the same storage volume (/virtserver/) is reused between runs the
values passed will be persisted. If the volume is persisted, reusing the environment variables VirtServerUser and VirtServerPassword will add or update the user database.

VirtServer Configuration

When running VirtServer in docker, the default location of the configuration file is in /virtserver/. When running
VirtServer with https, the default configuration file will be /virtserver/virt-server-docker-https.yml and when running
it using plain http the configuration will be in /virtserver/virt-server-docker.yml. By setting the environment variable
CONFIG (-e CONFIG=/virtserver/some-file.yml) it is possible to specify a different file (much be transfered to the
container volume). This requires the volume to be persistent from one run to another.

Using HTTPS for management

Unless running in a secure internal environment it is recommended that VirtServer is setup to use https instead of http
for the connection between the client (typically ServiceV) and the server. The default setup will be to use https. To used http instead, specify -e UseHTTPS=false.

Out of the box VirtServer ships with a pre-generated self-signed certificate. To generate a new (self-signed) certificate it is possible to run the docker image with -e CertificateSubject to instruct the start script to generate
and replace the default certificate with better values.

Using certificates which are not self-signed

Because self-signed certificates are good to hide traffic from network sniffers they add a bit more security than using
plain http traffic. However, in all other aspects they are considered insecure and most browsers will warn and end user
directing its browser to a https address with a self-signed certificate.
To learn more about how to install a more trusted certicicate, please refer to the VirtServer documentation at

Important: When running a docker image, it is important to persist the /virtserver storage volume between runs to keep the
certificates installed, users added, virts deployed and configuration changes persisted between restarts.
If you are running docker from the command line you can do this by using the
-v argument to docker run.


Because you need to communicate with VirtServer (both to control it and to talk to the virts) you also need to open some ports. This is done using the -p argument of docker run (or similar in an environment like docker cloud). With docker run, the command would look something like this:

docker run -v /opt/virtserver:/virtserver -p9090:9090 -p 8000-8010:8000-8010 -e UseHTTPS=true -e ACCEPT_TOU=true \
 -e VirtServerUser=admin -e VirtServerPassword=secret -e DockerUser=virtserver1 \
 -e VirtServerLicenseServer= smartbear/ready-api-virtserver

Breaking the line apart, this is what the pieces do:

Part Explanation
docker run We are running something
-v /var/virtserver:/virtserver Mount the volume /virtsever on the local file systems directory /var/virtserver
-p9090:9090 -p 8000-8010:8000-801 Publish the local port 9090 on the host's port 9090 and the range of ports 8000-8010 on the local ports 8000-8010 (for the virtualized APIs)
-e ACCEPT_TOU=true Accept the Terms of Use
-e VirtServerUser=admin -e VirtServerPassword=secret Make sure there is a user named admin with the password secret which we can use to log in
-e DockerUser=virtserver1 Use the user virtserver1 when checking out a license from the license server
-e VirtServerLicenseServer= The floating license server can be found at
smartbear/ready-api-virtserver The image to run, the VirtServer is tagged with its version so it is possible to get a specific version by referring to a tag like 2.0.2, or use latest for the latest release

Passing System Properties

You can pass arbitrary command-line arguments to the java process by providing env variables prefixed with "JVM_OPT_", for example if you want to provide a value for the server.port.http configuration property of TestServer you could define an environment variable named "JVM_OPT_HTTP_PORT" with the value "-Dserver.port.http=XXXX".

Exposing ports

Be sure to expose ports needed by your Virts!

Docker Pull Command

Comments (0)