Minimum Requirements for VM Installation

Last modified on June 22, 2022

SwaggerHub On-Premise 2.x can be installed on a virtual machine of your choice (Ubuntu, RHEL, Amazon Linux, and others). Both online and airgapped installations are supported.

If you are going to do airgapped (offline) installation, please contact Sales or your account manager before you proceed with the installation. We will send you a link to the download portal where you can download the installation files.

General requirements

To install SwaggerHub On-Premise, you need the following things prepared in advance:

  • A SwaggerHub license file (.yaml) provided to you by SmartBear. To request a trial license, contact Sales or your account manager.

  • An SMTP server to send user invitations and other emails from SwaggerHub. Trial users can use a temporary SMTP server.

  • A DNS name that you will use to connect to SwaggerHub. For example, swaggerhub.yourcompany.com. This domain must already be registered in your DNS service and must be routable on your network. You will need to point this DNS name to the VM IP address.

  • (Optional.) An SSL certificate to secure access to the Admin Console web interface. You can also install and update the certificate at any time later.

    VM installations currently support SSL termination only for the Admin Console but not for the SwaggerHub application itself. Full SSL termination support will be added in a future release.

VM requirements

The minimum requirements for a SwaggerHub On-Premise VM are:

  • Linux-based. See the list of supported operating systems.

  • 8 vCPU

  • 16 GB memory

  • 200 GB disk space

  • If the /var/lib/kurl directory already exists, it must be writable by the user who will perform the installation (that is, have 755 permissions).

  • The hypervisor must be running on a server or cloud infrastructure (that is, not a desktop computer or laptop).

You must have SSH or cloud shell access to this VM, with either root login or sudo permissions.

VM installations currently support only single node deployments.

Database requirements

SwaggerHub On-Premise can be configured with internal or external databases. Both databases have to be external or internal ones. Choosing a mix of internal and external databases is not supported.

If using external databases:

  • The databases must be provisioned in the same region where your SwaggerHub On-Premise VM is is located. The databases must be initially empty. SwaggerHub installation will create the necessary database tables.

  • You are responsible for backing up, maintaining, and securing external databases.

    External databases are not included in SwaggerHub snapshots. You must back them up separately using your corresponding database backup tools. Both databases have to be backed up at the same time to avoid data inconsistency when a data restore is needed.

External PostgreSQL

  • PostgreSQL 10 to 14
  • Memory: 16 GB
  • A user that has the ability to create databases. You can create such a user as follows:

    CREATE ROLE shubuser WITH CREATEDB LOGIN ENCRYPTED PASSWORD 'shubpassword'

External MongoDB

  • MongoDB 4.4
  • Memory: 16 GB
  • A user with the root privilege in the admin database.

Network connectivity

The following firewall configurations are required for inbound and outbound traffic to/from a SwaggerHub On-Premise VM.

To check connectivity from a VM, you can connect to it over SSH and then ping the target server, or telnet into the target server and port, or fetch the target URL using curl or wget. Note that ping will not work if ICMP is blocked on the target server or by your firewall.

Online installation and upgrades

Internet-connected VMs require outbound HTTPS Internet access (on TCP port 443) from the VM to the following domains in order to pull images, licenses, and product updates:

  • hub.docker.com
  • proxy.replicated.com
  • replicated.app
  • k8s.kurl.sh
  • amazonaws.com

Ongoing access

The following applies to both internet-connected and airgapped installations.

Inbound to the VM - required:

Port Protocol Source Purpose
22 TCP Administrator’s IP address or subnet SSH access to to the VM
80 TCP Users of SwaggerHub

Access to the SwaggerHub application.

Note: We recommend configuring HTTPS and redirecting all HTTP traffic to HTTPS.

8800 TCP Administrator’s IP address or subnet Access to the KOTS Admin Console

Outbound from the VM - required:

Destination Port Purpose
MongoDB database/cluster MongoDB port, for example, 27017 Database access
PostgreSQL database/cluster DB port, for example, 5432 Database access
SMTP server SMTP port To send invitations and email notifications
API servers specified in your OpenAPI definitions   To use the “try it out” feature in API documentation
$ref URLs   To resolve references to external OpenAPI documents hosted outside of SwaggerHub

Outbound from each the VM - optional (depends on the integrations and services used):

Destination Port Purpose
LDAP server LDAP port For single sign-on via Active Directory OpenLDAP
Backup storage   Backups created using Velero can be stored to a variety of storage providers. The configured storage must be accessible from each cluster node.
Webhook URLs   For outgoing webhooks
github.com
api.github.com
443 GitHub.com integration
self-hosted GitHub Enterprise Server   GitHub Enterprise Server integration
gitlab.com 443 GitLab integration
self-hosted GitLab server   GitLab integration
bitbucket.org
api.bitbucket.org
443 Bitbucket Cloud integration
self-hosted Bitbucket Server   Bitbucket Server integration
*.visualstudio.com 443 Azure DevOps Services integration
self-hosted Azure DevOps Server   Azure DevOps Server integration
apigateway.{region}.amazonaws.com 443 Amazon API Gateway integration
api.enterprise.apigee.com 443 Apigee Edge integration
self-hosted Apigee Edge server   Apigee Edge integration
*.management.azure-api.net 443 Azure API Management integration
apimanager.ussouth.apiconnect.cloud.ibm.com
login.service.us.apiconnect.ibmcloud.com
443 IBM API Connect integration

Proxy server

SwaggerHub On-Premise lets you specify a proxy server in the Admin Console. This proxy server will be used for outgoing HTTP/S traffic from SwaggerHub services, such as “try it out” requests, integrations, and outgoing webhooks.

Note: This proxy server is not used for non-HTTP traffic (such as SMTP) and traffic from KOTS services.

See Also

VM (Embedded Cluster) - Online Installation
VM (Embedded Cluster) - Airgapped Installation

Highlight search results