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.

Note

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.

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:

vm.max_map_count=262144
fs.file-max=65536

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.

Note

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 16

  • 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

  • External MongoDB

  • MongoDB 6 or 7

  • Memory: 16 GB

  • A user with built-in role: root, admin or readWriteAnyDatabase.

  • Alternatively, you can achieve this with a custom role. To do so, assign the user the following permissions:

    • serverStatus custom rule

    • readWrite and listCollections for the following databases:

      • swaggerhub_configs

      • swaggerhub_email

      • swaggerhub_operator

      • swaggerhub_standardization

      • swaggerhub_registry

      • swaggerhub_products

      • swaggerhub_plugins

      • serverStatus

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

In this section:
© 2024
Publication date: