VM (Embedded Cluster) - Airgapped Installation
Follow this guide to install SwaggerHub On-Premise on a virtual machine that is not connected to the internet.
Prerequisites
This guide assumes you already have a VM that meets the system requirements, along with other resources required for SwaggerHub installation. See Requirements for VM Installation.
We recommend that you create a VM snapshot before installing SwaggerHub. In this case, you will be able to reset the VM to its original state if the installation becomes corrupt.
Download installation files
Before you proceed with the airgapped installation, contact Sales or your account manager and ask for a link to download the installation files. You will receive a link and password to access the download portal. The link is customer-specific and looks like this:
https://get.replicated.com/airgap/#/kots/swaggerhub/<UNIQUE-ID>
On a computer with Internet access:
Log in to the download portal using the provided link and password.
Select Embedded cluster on the left.
Download the following files:
Your license
Latest kURL embedded install (
swaggerhub.tar.gz, 5.3 GB)Latest SwaggerHub Airgap bundle (
SwaggerHub-<version>.airgap, 3 GB)
 |
Install the Admin Console
First you need to install the KOTS Admin Console on the VM. The Admin Console will later be used to install and administer SwaggerHub On-Premise.
Copy the
swaggerhub.tar.gzfile to an existing temporary directory on the VM. For example, to/var/tmp/swaggerhub.scp swaggerhub.tar.gz username@VM:/var/tmp/swaggerhub/
Connect to the VM using SSH.
Extract the contents of
swaggerhub.tar.gzusingtar.cd /var/tmp/swaggerhub tar xvzf swaggerhub.tar.gz
Run the installation script:
cat install.sh | sudo bash -s airgap
The installation will take a few minutes to complete.
Notes:
The "Host preflight failed" error caused by
[FAIL] Filesystem Performance: Write latency is too high. p99 target < 10ms, actual:
can be ignored but consider using a faster disk.
The “SELinux is not installed: no configuration will be applied” error is expected on operating systems other than SELinux and can be ignored.
After the installation is complete, note down the password generated for the Admin Console. This password will not be shown again.
Note
You can change or reset this password later, as explained in Resetting the Admin Console Password.
To configure kubectl reload your shell:
bash -l
By default, kubectl is configured only for the user that ran the installation. If you wish to give another user access, then SSH in as that user and run:
mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config
Next, browse to http://<VM>:8800 to set up SwaggerHub On-Premise using the Admin Console.
Configure HTTPS for the Admin Console (Optional)
By default, the Admin Console at http://<VM>:8800 uses a self-signed certificate, which will cause a browser warning to appear every time you access the Console. The initial page informs you about this. Click Continue to Setup.
 |
Ignore the browser warning that appears.
 |
On the next screen, you can upload your own SSL certificate to secure access to the Admin Console.
If you want to continue with the default (self-signed) certificate, click Skip & continue. You will be able to add a certificate later.
 |
Note
The SSL certificate configured here is used only by the Admin Console and not by the main SwaggerHub application. The SSL termination support for the SwaggerHub application will be added in a future release.
Install and configure SwaggerHub
Upload the license
Proceed to log in to the Admin Console using the password that was previously generated for you.
On the next screen, you will be asked to upload your SwaggerHub license file (.yaml):
Upload airgap bundle
On the Install in airgapped environment screen, upload the SwaggerHub-n.n.n.airgap file to the indicated drop zone.
After the bundle has been uploaded, the Admin Console will start to process the images and manifests. Images will be loaded, re-tagged, and pushed to your Docker container registry. Wait until this process is complete.
 |
Configure SwaggerHub
On the next page, you can specify the configuration settings for SwaggerHub. The required settings for VM installations are:
DNS name for SwaggerHub - Specify a public or internal domain name that will be used to access SwaggerHub on your network. For example, swaggerhub.mycompany.com.
This domain name must already be registered in your DNS service. You will need to point it to the VM’s IP address.
Database settings - Choose between internal or external databases. If using external databases, you need to specify the database connection strings.
Important
It will not be possible to switch from internal to external databases or vice versa after the initial configuration.
SMTP settings - Specify an SMTP server for outgoing email.
Other settings are optional and depend on your environment and the desired integrations. Most settings can also be changed later. See SwaggerHub Configuration for a description of the available settings.
Click Continue at the bottom of the page to proceed.
Preflight checks
The next step checks your VM to ensure it meets the minimum requirements.
If all preflight checks are green, click Continue.
If one or more checks fail, do not proceed with the installation and contact Support.
 |
Status checks
While the installer allocates resources and deploys workloads, the application status on the dashboard will be Unavailable. If it stays in this state for more than 10 minutes, generate a support bundle and send it to the Support team.
 |
Tip: To monitor the deployment progress, you can run
kubectl get pods
a few times until all pods are Running or Completed:
NAME READY STATUS RESTARTS AGE kotsadm-85d89dbc7-lwvq2 1/1 Running 0 32m kotsadm-minio-0 1/1 Running 6 13d kotsadm-postgres-0 1/1 Running 5 13d spec-converter-api-584cc46657-hbfmd 1/1 Running 0 9m55s swagger-generator-v3-6fc55cb57d-brwg6 1/1 Running 0 9m55s swaggerhub-accounts-api-8bb87565b-xthkv 1/1 Running 0 9m55s swaggerhub-api-service-546b56b94b-6jxch 1/1 Running 0 9m55s swaggerhub-configs-api-794847bd79-jnlhl 1/1 Running 0 9m55s swaggerhub-custom-rules-5ccfd45599-d5bxc 1/1 Running 0 9m55s swaggerhub-frontend-69b7c55595-n7vsj 1/1 Running 0 9m55s swaggerhub-notifications-bbd5f8794-ggz99 1/1 Running 0 9m55s swaggerhub-operator-758c997747-hnjt7 1/1 Running 0 9m55s swaggerhub-pre-install-r9c2f 0/1 Completed 0 13d swaggerhub-pre-upgrade-cg664 0/1 Completed 0 10m swaggerhub-products-api-6dd446b654-7w7wn 1/1 Running 0 9m55s swaggerhub-registry-api-886997fd7-8q8c7 1/1 Running 0 9m54s swaggerhub-virtserver-79fdf54f98-wpmt8 1/1 Running 0 9m54s
Once the application has become ready, the status indicators on the Dashboard become green.
 |
Create admin user and default organization
Reload your shell:
bash -l
Run the following command to create an admin user and a default organization in SwaggerHub. Note the space in -- cmd.
Example:
kubectl exec -it deploy/swaggerhub-operator -- cmd create-admin-user admin -p p@55w0rd [email protected] myorg
The admin username must be between 3 to 20 characters and can only contain characters
A..Z a..z 0..9 - _ .The admin password must be at least 7 characters long with at least 1 lowercase letter and 1 number. If the password contains characters that have a special meaning in Bash (such as
! $ &and others), enclose the password in single quotes (like-p '$passw0rd') or escape the special characters.
Once done, open the SwaggerHub web application at http://VM_DNS_OR_IP and log in using the admin username and password. You should see the created organization in the sidebar:
 |
What’s next
Now that SwaggerHub is up and running, you can:
Add users to your organization in SwaggerHub and set their roles – either manually or using the User Management API.
Configure single sign-on using SAML, LDAP, or GitHub.