Install SwaggerHub On-Premise on VirtualBox

SwaggerHub On-Premise is distributed as a virtual machine that can be installed on VirtualBox. You can configure the SwaggerHub VM either via the VirtualBox GUI or from the command line. This guide explains both approaches.

Download

Download the latest SwaggerHub On-Premise OVA image:

go.gifhttps://onprem-downloads.swaggerhub.com/swaggerhub-vm-vbox.ova

and the security patch:

go.gifhttps://onprem-files.s3.amazonaws.com/log4j-patch.enc

You also need a license file to activate the instance during the installation. Contact your SmartBear sales representative or use the contact form to request a license for your trial or purchase.

Host requirements

To run SwaggerHub On-Premise, your VirtualBox host must meet the following requirements:

  • Must be a bare-metal server. VirtualBox running on a VM is not supported.

  • Dual-core CPU or better.

  • Memory: A SwaggerHub VM needs 16 GB of memory for production deployments or 8 GB for temporary proof-of-concept use. We recommend that the host have twice the VM’s memory, that is 32 GB for production use or 16 GB for proof-of-concept use.

  • 200 GB disk storage for the SwaggerHub VM.

Key points

The SwaggerHub On-Premise VM can work in the Bridged or NAT networking mode.

  • A Bridged VM gets its own IP address on the network.

  • If you use NAT, the VM shares the host’s IP address. You will need to expose VM port 80 via some host port (for example, 8000) by using port forwarding. The VM will be accessed via host:port, and VirtualBox will redirect the connections to VM:80. The selected host port must not be used by other applications on the host.

Deploy SwaggerHub VM using VirtualBox GUI

If you have access to the desktop environment, you can use VirtualBox’s GUI to import and configure the VM.

Note

The steps below are for VirtualBox v. 6. The steps for other versions may differ slightly.

  1. From the VirtualBox main menu, select File > Import Appliance.

    'File Import Appliance' menu in SwaggerHub

  2. Browse for the .ova file and click Next.

  3. Specify the following settings:

    • RAM – Change to 16384 MB for production deployment, or leave 8192 MB for temporary proof-of-concept deployment.

    • MAC Address Policy – Include only NAT network adapter MAC addresses.

    VirtualBox appliance import settings

  4. Click Import.

  5. Select the imported VM and click Settings.

    Opening VirtualBox VM settings

  6. On the Network tab, set the network adapter mode to either Bridged Adapter (recommended) or NAT.

    VirtualBox VM networking settings

  7. If you choose NAT, configure port forwarding for the ports used by SwaggerHub On-Premise:

    • Expand the Advanced section and click Port Forwarding.

      VirtualBox VM port forwarding options

    • Add the following rules:

      Protocol

      Host IP

      Host Port

      Guest IP

      Guest Port

      Comments

      TCP

      8000

      80

      For HTTP access to SwaggerHub

      TCP

      2222

      22

      Optional, for SSH access (supported since SwaggerHub On-Premise 1.19.1)

      Note

      If the above-mentioned host ports (8000 or 2222) are used by other applications on the host, specify other port numbers that are not in use.

    • Leave the Host IP and Guest IP blank.

    • Click OK.

  8. Click OK to save the changes.

Now you can start the VM:

  • Select the VM and click Start.

  • Wait until you see the following lines in the VM console:

    Access Installer UI at http://<IP_address>/ui/index.html Access Main UI at http://<IP_address>

See Configure SwaggerHub below for further steps.

Deploy SwaggerHub VM from command line

If you do not have access to the graphical desktop, you can set up a VM by using VirtualBox’s CLI tools.

1. Import the VM to VirtualBox

VBoxManage import --vsys 0 --memory 16384 --vmname swaggerhub-vm swaggerhub-vm-vbox.ova

Upon completion, you should see Successfully imported the appliance.

2. Configure the network

SwaggerHub On-Premise can operate either in the Bridged or in the NAT networking mode.

a. Bridged network

List the available bridged network interfaces:

VBoxManage list bridgedifs

Enable bridge networking and specify which network interface to use:

VBoxManage modifyvm swaggerhub-vm --nic1 bridged --bridgeadapter1 <name>

Refer to the VirtualBox documentation for more information about configuring the correct adapter and adapter type.

To verify the VM configuration on Mac or Linux:

VBoxManage showvminfo swaggerhub-vm | grep NIC

on Windows:

VBoxManage showvminfo swaggerhub-vm | find "NIC"

You should see something like this:

NIC 1: MAC: ..., Attachment: Bridged Interface '...', Cable connected: on, ...

b. NAT network

SwaggerHub requires that VM port 80 be exposed via a host port by using port forwarding. We recommend using host port 8000, provided that it is not used by other applications on the host.

If you need SSH access to the VM, you also need to expose VM port 22 via some host port, such as 2222.

Check which host ports are in use

As a pre-check, run this command to see which host ports are in use:

sudo nmap –sT –O localhost

or if you do not have nmap:

sudo netstat –vatn

or on Windows:

netstat -a -b

If the recommended host ports 8000 and 2222 are in use, specify other port numbers when configuring the port forwarding rules (see below).

Enable NAT and configure port forwarding

Run the following commands to change the VM to use NAT and forward host ports (marked with **) to VM ports. If the specified host ports are in use, you can use other port numbers that are not in use. Do not include ** in your command.

VBoxManage modifyvm swaggerhub-vm --nic1 nat --natpf1 "rule1,tcp,,**8000**,,80" --natpf1 "rule2,tcp,,**2222**,,22"

Verify network configuration

Run the following command to retrieve the configuration settings:

VBoxManage showvminfo swaggerhub-vm | grep NIC

You should see something like this:

NIC 1: MAC: ..., Attachment: NAT, Cable connected: on, ... NIC 1 Settings: ... NIC 1 Rule(0): name = rule1, protocol = tcp, host ip = , host port = 8000, guest ip = ,
                  guest port = 80 NIC 1 Rule(0): name = rule2, protocol = tcp, host ip = , host port = 2222, guest ip = , guest port = 22

3. Start the VM

VBoxManage startvm swaggerhub-vm --type headless

Configure SwaggerHub

Once the VM is up and running, navigate to the Admin Center at http://<VM_IP>/ui/index.html (in the Bridged mode) or http://<host_IP>:8000/ui/index.html (in the NAT mode; change the port accordingly). Follow the prompts to activate your license and configure the system. For details, see:

After the configuration is complete, the SwaggerHub web application will be available at http://<VM_IP> (in the Bridged mode) or http://<host_IP>:8000 (in the NAT mode).

If SSH access is required, it can be enabled through the Admin Center as explained here.

Post-installation patch

After the installation is complete, be sure to apply the security patch (log4j-patch.enc) to improve the security and stability of your SwaggerHub On-Premise instance.

  1. Upload and run the log4j-patch.enc patch on the System tab of the Admin Center, as explained here.

    Note: Since the patch file size is large, it will take a few minutes to upload to the Admin Center, and a few more minutes to execute. If you have a load balancer in front of your SwaggerHub On-Premise instance, you may need to increase the load balancer timeout so that the file upload does not time out.

  2. Wait for the following output to appear:

    ******************************************************************
The patch for CVE-2021-44228 and CVE-2021-45046 has been applied.
Please restart SwaggerHub to apply the changes.
******************************************************************

  3. Click Restart SwaggerHub.

See Also

In this section:
© 2024
Publication date: