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.
|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>
|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)|
*) 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.
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
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=18.104.22.168:1099 smartbear/ready-api-virtserver
Breaking the line apart, this is what the pieces do:
||We are running something|
||Mount the volume /virtsever on the local file systems directory /var/virtserver|
||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)|
||Make sure there is a user named admin with the password secret which we can use to log in|
||Use the user virtserver1 when checking out a license from the license server|
||The floating license server can be found at 22.214.171.124:1099|
||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".
Be sure to expose ports needed by your Virts!