Skip to main content

Install a Stand-Alone Web Gateway

If your web server is located on a separate machine from the InterSystems IRIS® instances which host your web applications, you can install the InterSystems Web Gateway on the web server machine as a stand-alone component.

This page describes the procedure for installing a stand-alone Web Gateway using the installation kit available on the WRC Components download page (https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab).

Note:

There are alternative methods for deploying a stand-alone Web Gateway on the web server machine in such a scenario, described elsewhere:

  • Use the InterSystems IRIS installer to install only the Web Gateway, selecting either a Custom setup type or (on Windows) a Web Server setup type.

  • Deploy a webgateway container.

In many cases, the stand-alone Web Gateway installer can configure your web server to use the Web Gateway automatically. Otherwise, the installation media provide the files necessary to add the Web Gateway to your web server configuration manually.

The stand-alone Web Gateway installer also allows you to specify connection information for an InterSystems IRIS instance. The stand-alone Web Gateway installer uses this information to create a server access profile for this instance as well as an application access profile for the instance prefix URL path. If the installer succeeds in connecting the Web Gateway to your web server automatically, it configures the web server to invoke the Web Gateway for all URL paths associated with the instance’s web applications, including the instance prefix URL path.

Step 1: Install a Supported Web Server

The Web Gateway installation kit can automatically configure a supported web server to use the Web Gateway, provided that it is installed and running prior to installing the Web Gateway. This is the recommended approach for most use cases.

The web server for which automatic configuration is supported varies depending on your system:

Important:

If you install a web server other than the one specified for your operating system, or if do not install the specified web server until after you have completed the Web Gateway installation, you will need to configure the web server manually.

Depending on your system, your web server installation may need to satisfy additional conditions to enable automatic configuration. See When is Automatic Configuration Possible?

Step 2: Download the Installation Kit

Stand-alone Web Gateway installation kits are distributed through the WRC Components download page (https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab).

Type web gateway in the Name column and then use the Os and Arch columns to locate the correct Web Gateway installation kit for your system.

For UNIX®, Linux, and macOS systems, InterSystems distributes the Web Gateway installation kit as a compressed tarball (.tar.gz) which contains an installation script (GatewayInstall); for Windows systems, InterSystems provides the installer as an executable file.

Step 3: (UNIX®/Linux/macOS Only) Extract the Installation Kit Files

Uncompress and extract the contents of the tarball into a temporary filesystem location. To do this while preserving the original permissions, you can issue the command below (replace <WebGatewayKit> with the name of the tarball you have downloaded):

tar zpxvf <WebGatewayKit>.tar.gz

The files extract into a directory with the same name, <WebGatewayKit>/. The contents of <WebGatewayKit>/ include:

  • An install/ subdirectory, which contains:

    • The installation script, GatewayInstall. The subsequent instructions on this page describe how to use this script to install the Web Gateway.

    • The nginx/ subdirectory. This subdirectory contains the file necessary to manually configure a build of Nginx which includes the Web Gateway.

  • A subdirectory with a name corresponding to your operating system and architecture, /<platformCode>. This subdirectory contains files necessary to manually configure an Apache httpd web server to use the Web Gateway.

    Note:

    The GatewayInstall script can automatically configure an existing Apache httpd web server to use the Web Gateway. Therefore, manual configuration is only necessary in atypical deployment scenarios, such as if you want to deploy a Web Gateway which uses the NSD.

Step 4: (UNIX®/Linux/macOS Only) Log in as root

To run the GatewayInstall script, you must be running a command line session as a user with root privileges. (It is sufficient to su as root from another user account.)

Step 5: Run the Installer

UNIX®/Linux/macOS

Run the GatewayInstall script to begin the installation process. You can do this by navigating to the <WebGatewayKit>/install/ directory and then issuing the following command:

./GatewayInstall

GatewayInstall provides a series of interactive prompts. As prompted, perform the following steps:

  1. Specify the type of web server you have installed:

    • Select Apache if you have installed Apache httpd and you would like the installer to automatically configure Apache to use the Web Gateway. The modified web server configuration will include directives invoking the Web Gateway for requests which are sent to relative URL paths associated with built-in InterSystems IRIS web applications.

    • Select None if you have installed any other supported web server, or if no web server is installed. When you select this option, the installer copies the files necessary to configure a supported web server manually into the directory you specify in the next step. It also configures the Web Gateway using the connection information you provide in a subsequent step. It does not attempt to configure a web server.

    Note:

    On some platforms, GatewayInstall may also prompt you to provide a string representing your system platform name. This string is provided at the end of the filename for the installation kit—for example: if your installation kit has the form WebGateway-<version>-lnxrh8x64.tar.gz, then lnxrh8x64 is the platform name. Alternatively, you can retrieve this value using the cplatname script. To do so, navigate to the installation kit’s /install subdirectory and issue the following command:

    # ./cplatname identify

  2. Specify your desired destination directory for the Web Gateway files, or accept the default (usually /opt/webgateway/). If the directory does not yet exist, the installer asks if you want to create it.

  3. Provide information about the InterSystems IRIS instance you would like the Web Gateway to connect to:

    1. The hostname for the machine where the instance is located.

    2. The superserver port where the instance accepts Web Gateway connections.

    3. The configuration name (CSPConfigName) for the instance. (By default, this is the instance name in lowercase characters.) The configuration name serves as a prefix URL path which can be used to route requests to that instance specifically.

    4. The security settings for the instance:

      • Select Minimal if the instance allows unsecured Web Gateway connections.

      • Select Normal if the instance requires Web Gateway connections to be authenticated using the instance’s CSPSystem user account credentials.

      • Select Locked Down if the instance requires Web Gateway connections to be authenticated using the instance’s CSPSystem user account credentials, and the security settings of the instance are Locked Down.

      If you select Normal or Locked Down, you must also provide the password for the instance’s CSPSystem user account.

    The installer uses this information to edit the Web Gateway’s configuration file (CSP.ini), creating a server access profile to connect to the instance and application access profiles for the instance’s applications (including one based on the instance’s configuration name).

    If the installer successfully configures your web server to use the Web Gateway automatically, it also uses this information to configure the web server. The web server configuration will include directives to invoke the Web Gateway for requests which are sent to the instance prefix URL path, based on the configuration name.

    Note:

    The installer requires responses for these prompts. If you are installing a Web Gateway before you have installed any InterSystems IRIS instance that it will serve, accept the default values or provide placeholder values. After the installation, you can remove the unneeded configuration items or modify them to connect to an existing instance.

  4. Confirm the configuration details to begin the installation.

Windows

Run the executable file to launch the standalone Web Gateway installer wizard. The wizard provides a series of interactive prompts. As prompted, perform the following steps, selecting Next > to advance to the next prompt:

  1. Select a setup type:

    • Complete installs all Web Gateway files in their default locations. In other words, it has the same effect as a Custom setup type (described next) wherein all installation features are included and no default location is overridden. If IIS is enabled, the installer configures IIS to use the Web Gateway.

    • Custom allows you to include or exclude installation features which install particular subsets of files, and select the directories where they will be installed:

      • Select Web Gateway CGI modules to install the files which implement the Web Gateway as a CGI extension. These files are generally not necessary unless your organization requires the exclusive use of CGI extensions.

      • Select Web Gateway for IIS to install the files which are necessary to configure an IIS web server to use the Web Gateway. If IIS is enabled and this item is selected, the installer configures IIS to use the Web Gateway. When configured, IIS will invoke the Web Gateway to handle requests which are sent to relative URL paths associated with built-in InterSystems IRIS web applications.

        Note:

        The installer always installs Web Gateway for IIS files within the default IIS directory (C:\inetpub\), whether or not IIS is enabled.

      • Select Static files for Web Gateway to install static files which are used by built-in InterSystems IRIS applications within the Web Gateway installation directory. This provides you with the option to configure the web server to serve these static files from a central filesystem location on the web server machine. (By default, each InterSystems instance serves files associated for its web application from its own directory.)

      • Select Web Gateway modules for Apache HTTPD servers to install the files which implement the Web Gateway as an extension for the Apache httpd web server.

        Caution:

        InterSystems no longer supports the use of the Apache httpd web server on Windows systems.

  2. Select Configure Web Gateway to connect to a server if you want the installer to configure the Web Gateway to connect to an InterSystems IRIS instance. When this option is selected, you can provide the following connection information about the instance:

    • Application name: a custom name which can be used as a URL path to route requests for the application or applications which the instance serves. In most situations, InterSystems recommends providing the instance’s CSPConfigName. (By default, this is the instance name in lowercase characters.)

    • IRIS server address: the hostname for the machine where the instance is located.

    • IRIS server port number: the superserver port where the instance accepts Web Gateway connections.

    • Connection password (optional): the password for the instance’s CSPSystem user account. (The CSPSystem user account is used to authenticate Web Gateway for instances installed with Normal or Locked Down initial security settings.)

    The installer uses this information to edit the Web Gateway’s configuration file (CSP.ini), creating a server access profile to connect to the instance and application access profiles for the instance’s applications (including one based on the Application name you specify).

    If the installer successfully configures your web server to use the Web Gateway automatically, it also uses this instance information to configure the web server. The web server configuration will include directives to invoke the Web Gateway for requests which are sent to the instance prefix URL path, based on the configuration name.

  3. Select Install to begin the installation.

Modify, Repair, or Remove a Web Gateway Installation

If there is already a stand-alone Web Gateway installed on your system, the stand-alone Web Gateway installation executable allows you to Modify, Repair, or Remove that installation.

  • Modify allows you to customize your installation, including or excluding installation features which represent particular subsets of Web Gateway files. These installation features are equivalent to those available for a new installation’s Custom setup type. Modify mode also provides you the opportunity to configure (or reconfigure) connection details for an InterSystems IRIS instance.

    If IIS is enabled and you Modify your Web Gateway installation to include the Web Gateway for IIS feature, the installer configures IIS to use the Web Gateway, as it does in a new installation. If you specify connection details for an InterSystems IRIS instance, the installer configures the Web Gateway and IIS to serve requests for that instance, as it does in a new installation.

  • Repair allows you to repair your stand-alone Web Gateway using its original installation settings, restoring any files which were deleted or corrupted. If your original installation included the Web Gateway for IIS feature but IIS was not yet enabled, Repair mode again attempts to configure IIS to use the Web Gateway. If your original installation specified connection details for an InterSystems IRIS instance but IIS was not yet enabled, Repair mode again attempts to configure the web server to serve requests for the instance.

  • Remove allows you to uninstall the stand-alone Web Gateway.

Next sectionExtend Your Web Server Configuration with the Web Gateway
Previous sectionOverview: Set Up a Web Gateway for Your System
FeedbackOpens in a new tab