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/kurldirectory 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
An admin user or a user with database creation rights (
CREATEDB). You can create such a user as follows:CREATE ROLE shubuser WITH CREATEDB LOGIN ENCRYPTED PASSWORD 'shubpassword'
In the case of a user with database creation rights: before installing SwaggerHub, connect to PostgreSQL with the user's credentials and create the
swaggerhub_accountsdatabase. Note that it should be provided in the connection string in Admin Console (for example,postgresql://user1:[email protected]:5432/swaggerhub_accounts).
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
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 | |
| 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.