Docker helps you run applications in virtual containers. Applications installed through Docker are platform-agnostic and can generally be installed by using a single command. SmartBear provides on-demand access to the ready-api-virtserver Docker image stored in DockerHub. This image can be used to quickly create a VirtServer instance and get to testing. This way you skip the default installation process.
Docker can be run on Windows either through VirtualBox or through Microsoft Hyper-V. Modern Docker versions use Microsoft Hyper-V by default, and use VirtualBox only if necessary. VirtServer can be run in both scenarios, but accessing a container run in VirtualBox requires additional VirtualBox configuration to expose it to your network.
To run virtual services in Docker, use the following image from Docker Hub:
Docker runs images in temporary containers that can be removed after they are no longer needed. If you had a Fixed license installed in the container, it would be lost. To avoid this, SmartBear disabled Fixed VirtServer licenses for Docker images. Instead, contact us and request a Floating license for your VirtServer instance.
Together with the Floating license, we will provide full access to the smartbear/ready-api-virtserver dockerhub repository that you use to download the image.
To deploy virtual services to VirtServer, you will need a ReadyAPI Virtualization Pro license.
This topic describes how to use Docker with ReadyAPI on the Hyper-V virtualization platform. To do that, use the same environment you use to run your Docker images. There are no specific requirements for this.
To learn more, see the Docker documentation:
To run ReadyAPI tools in Docker containers on other virtualization platforms, additional configuration may be required. Please see the corresponding documentation.
To start working with VirtServer in Docker, you need to pull the image from Docker Hub and start it.
Find the image in Docker Hub:
docker search smartbear/ready-api-virtserver
Pull the image to the local computer:
docker pull smartbear/ready-api-virtserver
To run VirtServer in a Docker container using a new legacy file based license, first run the docker login command and then use the following command line:
docker run -v /opt/virtserver:/virtserver -p 9090:9090 -p 8000-8010:8000-8010 -e VirtServerUser=User-Name -e VirtServerPassword=Smith -e VirtServerUserRole=admin -e DockerUser=VirtServerLicenseUser -e ACCEPT_TOU=true -e VirtServerLicenseServer=192.0.2.0:1099 http://docker.io/smartbear/ready-api-virtserver:latest
To run VirtServer in a Docker container using a new SmartBear ID-based license, first run the docker login command and then use the following command lines relative to where your license is hosted (replacing with your own values):
SmartBear ID-based license hosted on SmartBear license servers:
docker run -v /opt/virtserver:/virtserver -p 9090:9090 -p 8000-8010:8000-8010 -e VirtServerUser=User-Name -e VirtServerPassword=Smith -e VirtServerUserRole=admin -e DockerUser=VirtServerLicenseUser -e ACCEPT_TOU=true -e SlmAccessKey=101efa66-acea-4007-806a-c253cf901ete http://docker.io/smartbear/ready-api-virtserver:latest
SmartBear ID-based license hosted in customer on-premise license server:
docker run -v /opt/virtserver:/virtserver -p 9090:9090 -p 8000-8010:8000-8010 -e VirtServerUser=User-Name -e VirtServerPassword=Smith -e VirtServerUserRole=admin -e DockerUser=VirtServerLicenseUser -e ACCEPT_TOU=true -e SlmServerUrl= http://54.226.95.212:40892 -e SlmAccessKey=101efa66-acea-4007-806a-c253cf901et7 http://docker.io/smartbear/ready-api-virtserver:latest
Please add your own parameter values as appropriate.
The docker run command starts the docker container. Then, you specify the arguments. The command above includes basic arguments you need to start VirtServer.
docker.io/smartbear/ready-api-virtserver:latest
Required. The image to run. To get a specific VirtServer version, specify it in the tag instead of latest. You can omit docker.io/ at the start of the path.
-e VirtServerLicenseServer=192.0.2.0:1099
Required. The IP address and port of the license server.
-e ACCEPT_TOU=true
Required. Accept the SmartBear EULA before starting VirtServer. Must be true.
-p 9090:9090 -p 8000-8010:8000-8010
Required. Exposes ports 9090 and 8000-8010 to the same ports on the host computer. You need to expose port 9090 to work with VirtServer, and any ports you run the virtual services on (in this case, 8000-8010) to connect to them.
-e VirtServerUser=User-Name
Required for the first run and optional in subsequent runs. Creates a user on VirtServer. Can be omitted in subsequent runs as long as the volume persists. If specified, updates user information or creates a new user.
-e VirtServerUserRole=admin
Optional. Gives administrator rights to the created user. Recommended for the first run since only administrators can add new users.
-e VirtServerPassword=Password
A password for the created user. Can be omitted in subsequent runs as long as the volume persists. If specified, updates user information or creates a new user.
-e DockerUser=VirtServerLicenseUser
Optional. The name of the user who checks out the floating VirtServer license. You can see the user name in the License Manager. Default value: root.
-v /opt/virtserver:/virtserver
Optional. Commands Docker to create a shared file system (volume) for the VirtServer image. You can then create the /ext folder in the volume and place the .jar files you need to import in it.
For more information about working with Docker volumes, see the Docker documentation.
-e VirtServerClassPathExt=/virtserver/MyExt
Optional. The folder to load extension .jar files from. Default value: /virtserver/ext.
-e UseHTTPS=true
Optional. Commands VirtServer to use only HTTPS for connections to the client. By default, VirtServer uses a pre-generated self-signed certificate. Use the -e CertificateSubject command to generate a new self-signed certificate. Possible values: true, false. If no value is specified, VirtServer uses HTTP.
-e USAGE_STATISTICS=true
Optional. Commands the VirtServer to send usage statistics to SmartBear. Possible values: true, false. If no value is specified, the information is sent.
-e VirtServerClassPathExtras=sample:sample2
Optional. The additional elements to be added to the classpath when running VirtServer. Separate the elements with a colon.
-e CertificateSubject=/C=US/ST=MA/L=Somerville/O=SmartBear/OU=com/CN=virtserver.smartbear.local
Optional. The name properties for the generated self-signed certificate. If not specified, no certificate is generated.
Tip
For information on using certificates, see the Using Custom SSL Certificates topic.
-e CONFIG=/virtserver/newconfig.yml
Optional. The path to an alternative VirtServer settings file. If not specified, the default file is used.
-e JVM_OPT_Xmx=-Xmx2000m"
Optional. Additional JVM options for VirtServer. Full syntax: -e JVM_OPT_<UNIQUE_NAME>="<OPTION><VALUE>".
-e SlmServerUrl=ServerUrl:Port
Required only when using onpremise license server.. It is used for installing Smartbear ID - based License from the onpremise SLM license server. It should include the IP address and port of the SLM license server. If port is not specified it will automatically add default port for server on-premise 40892.
*Required only when your license is hosted onpremise. Do not include if your license is hosted on SmartBear license servers.
-e SlmAccessKey=AccessKey
Required for SmartBear hosted license or for onpremise license server when authentication required. Access key is required when using SmartBear hosted ID-based licenses or when license is hosted in onpremise license server option and Access for Everyone is switched off and authentication is enabled. It is not needed if your onpremise license server is configured for 'access to everyone'.
To run VirtServer in a Docker container using a legacy file based license:
docker run -v /opt/virtserver:/virtserver -e VirtServerClassPathExt=/virtserver/MyExt -p 9090:9090 -p 8000-8010:8000-8010 -e UseHTTPS=true -e VirtServerUser=User-Name -e VirtServerPassword=Password -e DockerUser=VirtServerLicenseUser -e ACCEPT_TOU=true -e VirtServerLicenseServer=192.0.2.0:1099 -e VirtServerClassPathExtras=sample:sample2 -e CertificateSubject=/C=US/ST=MA/L=Somerville/O=SmartBear/OU=com/CN=virtserver.smartbear.local -e USAGE_STATISTICS=true -e CONFIG=/virtserver/newconfig.yml -e JVM_OPT_Xmx="-DXmx=4000m" http://docker.io/smartbear/ready-api-virtserver:latest
To run VirtServer in a Docker container using a new SmartBear ID-based license use the following command lines relative to where your license is hosted (replacing with your own values):
SmartBear ID-based license hosted on SmartBear license servers:
docker run -v /opt/virtserver:/virtserver -p 9090:9090 -p 8000-8010:8000-8010 -e VirtServerUser=User-Name -e VirtServerPassword=Smith -e VirtServerUserRole=admin -e DockerUser=VirtServerLicenseUser -e ACCEPT_TOU=true -e SlmAccessKey=101efa66-acea-4007-806a-c253cf901ete http://docker.io/smartbear/ready-api-virtserver:latest
SmartBear ID-based license hosted in customer on-premise license servers:
docker run -v /opt/virtserver:/virtserver -p 9090:9090 -p 8000-8010:8000-8010 -e VirtServerUser=User-Name -e VirtServerPassword=Smith -e VirtServerUserRole=admin -e DockerUser=VirtServerLicenseUser -e ACCEPT_TOU=true -e SlmServerUrl= http://54.226.95.212:40892 -e SlmAccessKey=101efa66-acea-4007-806a-c253cf901et7 http://docker.io/smartbear/ready-api-virtserver:latest
After you start VirtServer, it runs in the container and cannot be found by ReadyAPI Virtualization automatically. You need to specify the connection manually. Depending on the Docker version you use, there are several addresses you can use:
Modern Docker versions attach to
localhostand redirect all requests to specified ports to the container. So, you can connect to it by using thehttp(s)://localhost:9090address.Docker Toolbox uses Oracle VirtualBox to create containers. To connect to a container in VirtualBox, you need to specify the VirtualBox IP address. Run the
docker-machine lsto see all your running docker machines. Then, use the IP address you received to connect to VirtServer at the VirtualBox address, for examplehttp(s)://198.51.100.0:9090.Important
To access VirtServer from other computers, you need to expose the VirtualBox machine to your network.
It is possible to configure VirtServer for OIDC in Docker. Please refer to the OIDC page for guidance.
To enable VirtServer in Docker to work with OIDC, VirtServer needs a virt-server.yml file containing the necessary OIDC configuration. This file will be provided to the VirtServer Docker container during startup. To do so, please follow these steps:
Create and set VirtServer in the OIDC provider.
Pull your Docker image for VirtServer.
Create a local folder, for example, oidcconfig, to store your configuration files.
Copy the virt-server.yml file to the oidcconfig folder. If you have VirtServer installed locally, you can find this file in the .readyapi directory. You can also rename the file to make it specific for your Okta. For more information, refer to this page.
Edit the virt-server.yml file to include your OIDC configuratione details and save the changes.
Mount the local folder (oidcconfig) to the internal folder /virtserver within the VirtServer Docker container using the docker volume flag
-v /opt/oidcconfig:/virtserver.Add the CONFIG environment parameter with the configuration file
-e CONFIG=/virtserver/virt-server.ymlpath of the VirtServer folder within the container.Start the VirtServer Docker container with the specified settings. Here's an example command:
docker run -v /opt/oidcconfig:/virtserver -p 9090:9090 -p 8000-8086:8000-8086 -e VirtServerUser=defaultUser -e CONFIG=/virtserver/virt-server.yml -e SlmAccessKey=dba42a79-aa44-4cc9-b2cd-005c69e272ea -e ACCEPT_TOU=true smartbear/ready-api-virtserverOnce the container is running, access VirtServer at https://localhost:9090/virtserver.
Log in to VirtServer using your OIDC credentials.
Note
When VirtServer is configured for OIDC, all user management is controlled and managed in your OIDC environment such as Okta. As a result, users cannot be added, edited, or removed using the WebUI or CLI in VirtServer. These options are disabled when OIDC configuration is in place. Please contact your OIDC Administrator, if you need to add a user to Virtserver.
Often, you would want to run VirtServer on your cloud service. Docker provides an integrated solution to running in a cloud by means of Docker Cloud.
To learn more about deploying services to Docker cloud, see the Getting Started tutorial in Docker documentation.