Skip to main content
Click here if you are having trouble viewing this site
Older versions of Internet Explorer will not support certain site features. Chrome, Safari, Firefox, and Edge will provide the best experience.
Resources
Spok

Installing and Configuring the On-Premises Gateway

  1. Last updated
  2. Save as PDF
This article describes installing the on-premises gateway on three or more virtual machines. The on-premises gateway provides a pipeline to move messages and data from existing on-site systems, including MediCall, Smart Suite, Spok Console, and Spok Messenger to Spok Go.

Gateway Overview

Show/Hide Gateway Overview

​

Overview

The on-premises gateway provides the secure, encrypted connection to Spok Go from on-premises systems including Spok products like Smart Suite, Spok Console, MediCall and Spok Messenger as well as other systems like EHRs and nurse call systems. The gateway is a thin application that moves data from the on-premises systems to the cloud. The gateway requires a minimum of three VMs (virtual machines) behind the customer's firewall. The VMs are then clustered for high-availability, redundancy and resiliency.

The gateway is deployed as a cluster of 3 redundant VMs and because it is the “thin application” that was mentioned before, it can continue functioning even after the possible loss of 2 VMs. To help ensure better resiliency in the event of unforeseen issues, the VMs on which the gateway is installed can reside on different virtualization servers so that the loss of a server does not affect all of a Gateway’s VMs. To further insulate the gateway’s continued operation from the unexpected, the virtualization servers that are used can even exist in different data centers (provided there is little-to-no network latency between the data centers that are involved).

You can add additional gateways if a site has multiple data centers or needs high throughput for messaging. A tenant can have multiple gateways, but a gateway can point to only one tenant. However, to allow the virtual machines to create a server cluster, there must be an odd number of virtual machines. An even number of machines will not allow a leader machine for the server cluster. Spok recommends one gateway (set of three virtual machines) per data center or console/middleware system. 

Each virtual machine should be allocated the recommended disk space, memory, and processor. To help ensure performance and throughput, ensure other applications on the VM do not use or limit these resources.

Gateway Requirements

The customer must provide the following for the gateway:

Requirement Details
Virtualization Software/Hypervisor

VMWare

The on-premises Gateway’s installation package is distributed as an OVA file using the OVA standard. While VMWare is the only Virtualization Software/Hypervisor that has been tested thus far, any Virtualization Software/Hypervisor that supports installations via the OVA standard resulting in Ubuntu VMs should suffice.
Virtual Machines

A minimum of 6 (3 for production tenant and 3 for the test tenant) with the following:

  • Internet access
  • 40 GB of disk space
  • 4 GB of RAM
  • 2 CPUs
Load Balancer A load balancer such as HAProxy is needed to manage the traffic for both production and test gateways. For more information, see Preparing for Spok Go > Load Balancer.

Gateway Software 

The table below lists the software that is included with the gateway:

Software Details
Operating System Ubuntu1 
Gateway Components2 Containerized software components for connectors that enable integration with on-site systems. These include Spok systems such as MediCall, Spok Messenger, Spok Console, and Smart Suite,  as well as other on-site systems like EHRs, Lab and Radiology systems, Nurse Call systems, and similar.
  1. This operating system is included as part of the gateway installation and does not need to be provided by the customer. Spok will automatically install and perform any security or maintenance updates to the operating systems on the virtual machines on a weekly basis. The security and maintenance packages that are installed are retrieved directly from Ubuntu’s default package repositories. In order to ensure uptime, these packages are applied to one virtual machine at a time so that if a restart of a service or a virtual machine is necessary, the other two instances of the Gateway will continue to be available to service any message, alarm or other Gateway traffic.
  2. Spok will automatically install and perform any updates to the Gateway components on an as-needed basis. The updates that are installed are retrieved directly from the Spok Go Platform in AWS. In order to ensure uptime, these updates are applied to one virtual machine at a time so that if a restart of a service or a container is necessary, the Gateway software that is running on the other two instances of the Gateway will continue to be available to service any message, alarm or other Gateway traffic.
​

Security

To enhance security, there is one outbound connection from gateway to the cloud. Traffic from the internet cannot be sent down through the gateway. A port does not need to be opened on the customer side. Any data coming into or leaving the gateway is encrypted.

All communication between Spok Messenger, Spok Console, and Smart Suite to the gateway is encrypted. The gateway does not store any data on the virtual machines because it acts as a pipeline to quickly move data to cloud.

 

This article displays the network diagram for Spok Go.

The diagram below shows the network diagram for integrating Spok Go. A load balancer is required to route all messages/information into the gateway, which is installed on three separate virtual machines. 

This Network Diagram is for informational purposes only. The integrations that are shown represent what is possible even though they may or may not be used by, or available to, every customer, installation, or environment (ex: production vs. test).

Visio Download

clipboard_e300b611e6a86c9945d15c5caa03cc02e.png

 

Before you Begin

Before you can install and configure the on-premises gateway, you need the following:

  • Access to VMWare at the customer site. 

  • A customer-provided, signed PKCS12 (PFX) X509 SSL certificate.

    • Because Spok does not embed a private key in the Gateway, this certificate and its private key must be provided by the customer and should be available at the time of the Gateway’s installation

    • The certificate should use the Fully Qualified Domain Name (FQDN) or IP address of the load balancer.

    • The corresponding root and/or public version of the certificate should also be recognized as a trusted certificate in the operating systems of any on-premises systems (ex: Smart Suite, Messenger, etc.) that are communicating with the Gateway.

  • A load balancer to manage gateway traffic.

    • Simple round-robin load balancing between the three virtual machines for the gateway is sufficient.

    • The Fully Qualified Domain Name (FQDN) or IP address of the load balancer needs to be known at the time of Gateway’s installation and added to the customer’s DNS.

    • The on-premises gateway's virtual machines must also be added the load balancer's configuration (sometimes known as a "Resource Pool").

    • Any HTTPS traffic should pass through the load balancer, with the SSL termination occurring in the on-premises gateway. It is not necessary to load the SSL certificate on the load balancer.

  • An active customer tenant/organization within Spok Go. 
  • A user account that has Spok System Administrator or Spok Support Administrator security role for the applicable customer organization. 
  • MediCall 11.12 or higher, Smart Suite 7.1.2 or higher, Spok Console 7.11 or higher, and/or Spok Messenger 5.16 or higher installed and configured.

  • In order to support regular maintenance and automated updates, outbound internet access from the Gateway’s VMs to specific sites is also required. See Firewall Requirements for requirements.

Spok strongly recommends using a DHCP server with the VM server to assign an IP address to each instance of the gateway and to access the internet. If a DHCP server is not available, additional configuration of the on-premises gateway is required to assign the IP addresses.

Step 1: Create the Gateway

Access Spok Go to create the gateway.

  1. In Spok Go, click Administration > Integrations > Gateways tab.
  2. Click +Gateway to add the gateway.
  3. In the Gateway Management page, enter the Gateway Name. This name can be edited later if needed.
  4. Click Save.

Delete the Gateway

In the future if you like to delete the gateway, click Delete this gateway permanently. This will permanently delete the gateway so be sure only to select this if the connector is not needed.

Step 2: Creating the Virtual Machines and Installing the Gateway

An OVA file is used to create and set up the virtual machines. The OVA file contains all of the files needed to create/deploy the virtual machine and the gateway components. Download the OVA file and import it into the virtualization program to create a virtual machine.

Downloading and Importing the OVA File

To ensure the latest version is used, download a new copy of the OVA file immediately prior to each installation.

  1. Go to Integrations > Gateways tab, click OVA. Choose Save File. The OVA file is downloaded.
  2. Sign in to the virtualization software at the customer site. 
  3. Import the OVA file into the virtualization software. The same OVA file is used to create each machine. 
  4. Enter a name for the gateway, such as SpokGo-gateway-node1. The virtual machine is created. It may take 15 minutes to install the gateway. 
  5. Repeat steps 2-4 to create two more virtual machines. 
  6. Within the virtualization software, verify each of the three machines is visible and running.

 

Optional Step: Updating the VM IP Addresses

The virtual machines will have DHCP enabled by default. Modifying this configuration is possible using the provided gateway command line script.  
 
To use the script:

  1. Connect to the virtual machine as the gatewayadmin user.
    Contact support for the initial gatewayadmin password. Once the gateway software is deployed, the password is regularly rotated for security and can be retrieved from the gateway administration page by authorized users.
    The gatewayadmin user can only be used in a console session. SSH access for this user is disabled.
  2. Use the gateway command line script to configure networking settings.
    To view instructions for the script, log in as the gatewayadmin user and type: sudo gateway -help

The gateway command line script provides the ability to configure static or DHCP addressing through IPV4.  IPV6 support is experimental.

 

Step 3: Registering the Gateway Nodes

Registering the gateway nodes within Spok Go assigns it to a specific customer. It also allows remote management, software updates, and patches.

Registration requires an activation code and ID to authenticate and identify the machines. The activation code does not need to be updated after the machines are registered. (The code does need to be used within 24 hours.) However, if you add new or additional virtual machines after the code has expired, a new code is needed to add the new machine.

Getting the Activation Code and ID

  1. Go to Activation Key for your gateway and click Show Key.
  2. Copy the Activation ID and Activation Code for use in the Registering the Gateway steps.

Registering the Gateway

  1. Go to the admin URL for each of the gateway nodes (example: https://0.0.0.0:8443/api/admin/help) and click Authorize.
    1. Sign in using the admin account. If you don't have a password, contact the Spok Development team.
    2. Click Authorize again to login.
  2. Open the Activation Put endpoint /api/admin/v1/Activation and click Try it out.
  3. Paste the Activation ID and Activation Code from the previous steps into the "string" fields.
  4. For the awsRegion, enter "us-east-1" for US customers, "ap-southeast-2" for Australia customers, or "ca-central-1" for Canadian customers into the "string" field.
  5. Click Execute. A success code is returned and the gateway node is registered with AWS.

If you receive the error response "TypeError: Failed to fetch", refresh the swagger page and restart at step 1 of this section.

  1. Repeat these steps on each virtual machine using the same activation code and ID for each virtual machine. The three virtual machines now have a secure connection to the Spok software in the cloud.
  2. The Gateway tab will auto-refresh every 30 seconds. You can also reload/refresh the Gateway tab in your browser so that the activated gateway nodes are displayed as connected and online.

Deploy the Gateway

  1. In Spok Go, click Administration > Integrations > Gateways tab.
  2. Click the gateway in the list and click Deploy. Note that you must have all three nodes to deploy the gateway.
  3. Once a deployment has been started, you can click the drop down arrow to see updates for each node during deployment. After the process has finished on each node, you can see detailed logs of the process for each node.
  4. Once the deployment is finished, the Update button is visible. This allows you to update to the latest version of gateway software. Check with your Spok representative to determine when updates are available.

Step 4: Enabling HTTPS 

The following steps secure the communication from applications like Spok Messenger or Smart Suite to the on-premises gateway. You need to use the certificate from the customer. 

This step only needs to be run on one of the Gateway VMs. The loaded certificate will auto-propagate to the other VMs after that.

  1. Go to the admin URL for one of the gateway nodes (example: https://0.0.0.0:8443/api/admin/help) and click Authorize.
    1. Sign in using the admin account. If you don't have a password, contact the Spok Development team.
    2. Click Authorize again to login.

  2. Open the Certificate Post endpoint /api/admin/v1/Certificate and click Try it out.

  3. Click Browse, select the file containing the certificate’s private key on the system and click Open.

  4. Enter the password for the certificate file. Note that characters ' and $ are not accepted for the password.

  5. Click Execute. The certificate is now uploaded and displays a success message. The on-premises gateway can now connect to Spok Messenger or Smart Suite. Note that the gateway will not accept requests until this step is complete.

If you receive the error response "TypeError: Failed to fetch", refresh the swagger page restart at step 1 of this section.

Optional Step: Enable SFTP

This opens an SFTP server on the gateway that can be used with connectors.

  1. In Spok Go, click Administration > Integration > Gateways.
  2. Click the Gateway > Gateway Services tab.
  3. Enable SFTP by sliding the toggle and click Save. The Username and Password are now available to copy for use with Data Exchange.

Gateway Instance Status

The Gateway instance status is retrieved when the Spok Go application initially loads. It is displayed in both the Spok Go gateway and details screens.

Overall Instance Status

In the Gateways screen, the overall status of the three instances is shown.

The left side shows the overall Connection Status for the instances.

Overall Gateway Statuses

 

Condition

 

Inactive

 

0 instances or 3 instances BUT 1 or 2 are Inactive

Online

 

ALL 3 Instances are Online

In Progress

 

Less than 3 instances BUT they're all Online

 

Connection Errors

 

1 or more instances has status ConnectionLost

 

Deployment Instance Status

The right status indicator shows the overall Deployment Status for the instances. If a new gateway has not yet been deployed it will show the Not Deployed status until deployed.

Deployment Status Condition
Not Deployed Deployment has not started. This indicates a new gateway has not yet been deployed.
In Progress The deployment is in progress.
Deployed The deployment succeeded.
Deploy Failed Deployment was unsuccessful.

Detailed Instance Status

To see a more detailed view of the status for each instance, click the gateway. The details are shown next to the IP Addresses.

Additional information regarding background updates is available for each gateway node. This information may be useful to Spok support for troubleshooting purposes.

Below is a list of the detailed instance statuses and their definitions.

Status Condition
Connection Lost The node was activated but AWS is reporting back it’s unable to connect to the manager.
Inactive Instance is inactive.
Online Instance activation successful.

 

Summary

After completing these steps, the gateway should be:

  • Visible and running as three instances within the virtualization software.
  • Made up of three nodes running on distinct virtual machines which are communicating with each other.
  • Communicating with AWS and registered/assigned to the customer.

Next Steps

After the on-premises gateway is installed and configured, you can configure the gateway to communicate with other on-site applications, including Smart Suite and Spok Messenger. To do this, see Integrating MediCall with Spok Go, Integrating Spok Messenger with Spok Go, Integrating Spok Console with Spok Go, or Integrating Smart Suite with Spok Go for more information.