Minimum Requirements for VM Installation

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, 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.

Enhanced Search requirements

Enhanced Search allows users to have a better experience when searching for documents with SwaggerHub. Before enabling Enhanced Search, two operating system kernel parameters need to be set to minimum values.

  • vm.max_map_count: set to a minimum value of 262144. For sample commands consult the Virtual memory page in the Elasticsearch documentation.

  • fs.file-max: set to a minimum value of 65536. For sample commands consult the File Descriptors page in the Elasticsearch documentation.

For example, you might add the following to the bottom of your /etc/sysctl.conf file:


These parameters must be correctly set before installation, so after adding them to /etc/sysctl.conf, you will either need to reboot or issue the sysctl --system command.

VM requirements

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

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

  • 4 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.


Sudo permissions are required only for the installation and upgrade process. Sudo permissions can be revoked when the Embedded Cluster is already installed. More information can be found in the Install the Admin Console section.

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 11 to 14.6

  • Memory: 16 GB

  • A user that has the ability to create databases. You can create such a user as follows:


External MongoDB

  • MongoDB 4.4 or 5.0

  • 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:






Ongoing access

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

Inbound to the VM - required:







Administrator’s IP address or subnet

SSH access to to the VM



Users of SwaggerHub

Access to the SwaggerHub application.

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



Administrator’s IP address or subnet

Access to the KOTS Admin Console

Outbound from the VM - required:




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):




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

443 integration

self-hosted GitHub Enterprise Server

GitHub Enterprise Server integration


GitLab integration

self-hosted GitLab server

GitLab integration


Bitbucket Cloud integration

self-hosted Bitbucket Server

Bitbucket Server integration



Azure DevOps Services integration

self-hosted Azure DevOps Server

Azure DevOps Server integration



Amazon API Gateway integration


Apigee Edge integration

self-hosted Apigee Edge server

Apigee Edge integration



Azure API Management integration


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

Publication date: