Overview: Set Up a Web Gateway for Your System
To serve an InterSystems web application, you must configure a web server to route requests from a web client (such as a web browser) to an InterSystems IRIS® application server through the InterSystems Web Gateway.
In many cases, installers for both InterSystems IRIS and a Web Gateway can perform most of this configuration automatically. See Access Built-In Web Applications Using Your Web Server.
For users upgrading an InterSystems IRIS instance from an instance which uses the Private Web Server (PWS), videos which demonstrate the ease of automatically configuring a web server using the InterSystems IRIS installer are available here: https://learning.intersystems.com/course/view.php?id=2333Opens in a new tab
The process of manually setting up a connection between your web server and one or more InterSystems IRIS instances consists of the following procedures:
-
Install the Web Gateway files, or acquire the Docker image for the webgateway container.
-
Within your web server configuration, specify which requests your web server should route through the Web Gateway.
-
Within your Web Gateway configuration, register a server access profile for each InterSystems IRIS application server you want to serve web applications.
-
Within your Web Gateway configuration, register an application access profile to associate an application path with the InterSystems IRIS application server (or servers) which serve the application (or set of applications) available at that path.
-
Secure the connections between the client and the web server, between the Web Gateway and your InterSystems IRIS instances, and between a client and the Web Gateway management pages.
This page provides an overview of these procedures. For each procedure, it provides links to more specific instructions as needed. It concludes with a summary of how to decommission a Web Gateway.
Install the Web Gateway Files
Install a copy of the Web Gateway for each web server in your system. Depending on your needs, you can deploy the Web Gateway as part of an InterSystems IRIS installation, as a stand-alone component, or as a webgateway Docker container.
In many cases, the InterSystems IRIS installer and the stand-alone Web Gateway installer can automatically configure the Web Gateway to connect to your web server. This minimizes the need to perform the setup steps on this page, as follows:
-
For the stand-alone Web Gateway, the installer can automatically add the Web Gateway to the web server configuration. You must manually configure your web server to invoke the Web Gateway as a handler for your InterSystems web applications, including each InterSystems IRIS instance’s built-in system applications.
-
For an InterSystems IRIS instance, the installer can automatically add the Web Gateway to the web server configuration and automatically configure your web server to invoke the Web Gateway as a handler for the instance’s built-in system applications. Depending on your system, certain tasks must be performed manually to complete the configuration, as noted in Automatic Configuration Behavior. Once this configuration process is complete, you can easily extend it to suit the needs of your custom applications.
-
In all cases, you must configure connection security manually.
Install as Part of an InterSystems IRIS Installation
InterSystems IRIS provides access to several important system functions through web applications such as the Management Portal. For this reason, the InterSystems installer includes the necessary Web Gateway files as part of the following setup types:
-
Development
-
Server
-
Web Server (on Windows)
-
Custom, if the Web Server Gateway component is selected
Install as a Stand-Alone Component
If you would like to deploy your web server on a separate machine from the machines that host your InterSystems IRIS instances, install the Web Gateway on your web server machine as a stand-alone component in one of the following ways:
-
Run the stand-alone Web Gateway installer. This installer is available on the WRC download page (https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab). Simply type web gateway in the Name column and locate the kit for your system. As with the InterSystems IRIS installer, InterSystems implements the stand-alone Web Gateway installer as an executable file for Windows and as a script (GatewayInstall) for all other systems.
-
Run the InterSystems IRIS installer using one of the following setup types:
-
Web Server (on Windows)
-
Custom, selecting only the Web Server Gateway component
-
-
Pull the Docker image for a webgateway container from the InterSystems Container RegistryOpens in a new tab. See Deploy a webgateway Container for more information.
In many cases, the stand-alone installer provides you the option to automatically configure your web server to use the Web Gateway. After automatic configuration, no further action is needed to add the Web Gateway to your web server configuration. However, you must manually configure your web server to invoke the Web Gateway as a handler for your InterSystems web applications, including the built-in system applications for each of the InterSystems IRIS instances in your system. You must also manually configure connection security.
Deploy a webgateway Container
The InterSystems Container RegistryOpens in a new tab provides Docker images for webgateway containers. These containers include a web server (Apache or nginx) that is already pre-configured with a Web Gateway extension.
To configure a Web Gateway connection using a webgateway container, your configuration must satisfy the same conditions described in the sections which follow. However, in a containerized deployment, the configuration methods vary considerably from the methods referred to on this page. When you use the webgateway container:
-
No further action is required to add the Web Gateway to the web server configuration.
-
To automate web server configuration upon deployment, you should configure the web server in the webgateway container to invoke the Web Gateway for requests sent to particular paths by amending the configuration file programmatically within the image’s Dockerfile or by describing the configuration in the YAML file for the container cluster.
-
To automate Web Gateway configuration upon deployment, you can leverage the CSP.ini merge feature to define server access profiles and application access profiles for webgateway containers directly within their CSP.ini files.
Refer to Using the InterSystems Web Gateway Container for specific instructions.
Extend the Functionality of Your Web Server with the Web Gateway
When a web client requests static content (plain text, images, JavaScript), the web server’s role is straightforward: it simply serves content from the file system location that corresponds to the request’s URL path. The web server’s configuration defines mappings between URL paths and the file system locations which it has permission to access.
However, to serve dynamic content from a web application, you must extend a web server’s functionality with a library module or an external program that can interpret an HTTP request as a call to invoke web application code.
This is the purpose provided by the InterSystems Web Gateway: it extends a web server’s functionality to recognize and serve requests for InterSystems web applications. For a web server to serve an InterSystems IRIS web application, you must configure the web server to include the Web Gateway extension and then configure it to recognize which requests the Web Gateway extension should handle, usually based on the URL path specified by the request.
Add the Web Gateway to Your Web Server Configuration
InterSystems Supported Technologies page lists the web servers compatible with this version of the product. In many cases, the InterSystems IRIS installer can add the Web Gateway to your web server automatically.
The procedures for adding the Web Gateway to your web server manually vary considerably depending upon your operating system, the web server you use, and your use case. Some initial considerations:
-
In general, InterSystems implements the Web Gateway extension for a web server as a pair of binaries: one binary is responsible for core runtime functionality; the other is responsible for the functionality of the Web Gateway management pages. The management binary is distinguished from the runtime binary by the addition of Sys to the end of the filename (for example, CSPa24.so and CSPa24Sys.so). Both binaries must be in the same directory.
-
For Apache (UNIX®/Linux/macOS) and Microsoft IIS (Windows), the most straightforward way to deploy the Web Gateway is to leverage the web server’s proprietary API for adding dynamically-loaded extension modules—.so files for Apache, .dll files for IIS. Nginx (UNIX®/Linux/macOS or Windows) only supports adding the Web Gateway extension by building the extension’s source code into the web server at compilation time.
-
The Web Gateway extension for Nginx invokes an external process that performs the Web Gateway’s functions. This process is called the Network Service Daemon (NSD). If you must detach the operation of the Web Gateway from your web server, InterSystems also provides extensions for deploying an NSD Web Gateway with Apache and Microsoft IIS, using their respective proprietary APIs.
Important:For security reasons, the NSD files should not be accessible by your web server’s processes. InterSystems recommends installing the NSD files in a file system location outside of the directories which your web server processes can access.
-
If you must use Common Gateway Interface (CGI) extensions, InterSystems also provides CGI executables for configuring an NSD Web Gateway for Apache and Microsoft IIS.
-
Regardless of the deployment method you choose, you must configure your system so that your web server worker processes have adequate permissions to access the following directories (and their contents):
-
the installation directory for the Web Gateway binaries. By default, these locations are /opt/webgateway on UNIX®/Linux/macOS and C:\Inetpub\CSPGateway on Windows.
-
the directory which contains the Web Gateway configuration file (CSP.ini).
-
the /temp subdirectory within the Web Gateway installation directory, which records the contents of the Web Gateway cache in the form of .dat files.
-
the directory for any static files which your web application may serve. Static files associated with CSP applications are stored in corresponding directories within the <IRISinstallDir>/csp/ path, where <IRISinstallDir> is the installation path for the InterSystems IRIS instance which hosts the application. The <IRISinstallDir>/csp/broker path contains static files for several built-in system applications.
-
The following table provides links to specific instructions for adding the Web Gateway to your web server configuration, based on your operating system and your web server. For further information specific to your web server, refer to the web server’s product documentation.
Operating System | Web Server | Deployment Instructions |
---|---|---|
UNIX®/Linux/macOS | ApacheOpens in a new tab |
|
UNIX®/Linux/macOS | nginxOpens in a new tab | |
Windows | IISOpens in a new tab |
|
Windows | nginxOpens in a new tab |
Specify Which Requests the Web Server Routes through the Web Gateway
To serve an InterSystems web application, the web server must invoke its Web Gateway extension to handle HTTP requests which it receives at URL paths designated for that application. This configuration procedure varies depending on the web server.
Regardless of your web server, InterSystems provides two methods for specifying which requests the Web Gateway should handle:
-
Invoke the Web Gateway when the client requests certain file types at a given path. Requests for many InterSystems web applications end with one of the following InterSystems file type extensions:
.csp .cls .zen .cxw
The first three file types indicate different kinds of code which can run within InterSystems IRIS. The last file type (.cxw) is reserved for use by the Web Gateway management pages exclusively. If your web application serves static files as part of its response (.jpg, .js, and so on), you must configure the web server to invoke the Web Gateway in response to requests for those static file types as well.
-
Invoke the Web Gateway for any request at a given path.
Most REST APIs expose endpoint paths without specifying a file or file type (for example, the endpoint for collecting InterSystems IRIS performance data: /api/monitor/metrics). To serve such an application, you must invoke the Web Gateway for all requests at the application’s URL paths.
The following table briefly summarizes both methods of invoking the Web Gateway for each of the supported web servers. For more detailed instructions on configuring your web server, refer to your web server’s product documentation.
Web Server | Route all Requests at Path | Route for Certain File Types |
---|---|---|
ApacheOpens in a new tab |
Edit the Apache configuration file (usually httpd.conf) using the directives CSP On and CSP Off within a <Location> block. For example:<Location {/path}> CSP On </Location> where {/path} represents the relative URL path.
Note:
You cannot use this web server directive within a <VirtualHost> block |
Edit the Apache configuration file (usually httpd.conf) using the directive CSPFileTypes within a <Location> block. For example:<Location {/path}> CSPFileTypes {xxx yyy ...} </Location> where {/path} represents the relative URL path and {xxx yyy ...} represents a list of file type extensions separated by spaces.
Note:
You cannot use this web server directive within a <VirtualHost> block |
IISOpens in a new tab | Add an unrestricted * (wildcard)Handler Mapping invoking the Web Gateway Native Module. See Set Handler Mappings for Application Requests for details. | Add file-restricted Handler Mappings for the desired file extensions. See Set Handler Mappings for Application Requests for details. |
nginxOpens in a new tab |
Edit the nginx configuration file (nginx.conf) using the directives CSP on and CSP off. For example:location </path> { CSP on; } where </path> represents a relative URL path. See Configure Nginx to Invoke the NSD for details. |
Edit the nginx configuration file (nginx.conf) using the directive CSPFileTypes. For example:location </path> { CSPFileTypes <xxx yyy ...> } where </path> represents a URL path and <xxx yyy ...> represents a list of file type extensions separated by spaces. See Configure Nginx to Invoke the NSD for details. |
InterSystems recommends that you consider the full process of routing application requests from your web server to the InterSystems IRIS instance which serves your application before you choose the URL paths for which your web server will invoke the Web Gateway. This is especially true if your system features multiple InterSystems IRIS application servers or if your organization has specific URL naming conventions. See Choose the Paths Which Route Requests Through the Web Gateway for guidance.
Direct Requests from the Web Gateway to Your InterSystems IRIS Instances
After the web server passes a request for a web application to the Web Gateway, the Web Gateway routes it to an InterSystems IRIS instance which hosts the code for that application.
To do this, you must provide the following information to the Web Gateway:
-
connection information necessary to communicate with the application server process for each instance. The Web Gateway maintains this information in a server access profile.
-
mappings between a web application path (or a base path for a set of web applications) and the server access profile for the instance which hosts the application code. The Web Gateway maintains the routing behavior for a path in an application access profile.
The application server process for an InterSystems IRIS instance is sometimes referred to as a “CSP server,” in reference to the legacy InterSystems web application framework.
The Web Gateway management pages for configuring and monitoring connections to instances’ application server processes refer to these processes simply as “servers.” (The Web Gateway’s connection to the web server is determined by the web server configuration.)
To minimize confusion, the Web Gateway documentation refers to an InterSystems IRIS instance as the effective target of a Web Gateway connection, except where it is necessary to refer to the application server process specifically.
Regardless of the deployment, every Web Gateway provides the same convenient web interface for configuring server access profiles and application access profiles: the Web Gateway management pages. The Web Gateway management pages also allow you to configure global default parameters, monitor Web Gateway connections, test connections, and more.
The Web Gateway maintains configuration information in the CSP.ini file.
Except in containerized deployments where it may be necessary to edit the CSP.ini file directly, InterSystems recommends restricting access to the CSP.ini file and performing all Web Gateway configuration using the Web Gateway management pages or using Web Gateway Registry methods.
Connect InterSystems IRIS Instances to the Web Gateway
To allow the Web Gateway to establish and maintain connections to the application server process for an InterSystems IRIS instance, you must define a server access profile which provides connection information for each instance—IP address, superserver port number, connection security credentials, and so on. See Define a Server Access Profile for Your InterSystems IRIS Instance.
Associate Instances with an Application
A single Web Gateway can route requests to multiple InterSystems IRIS instances for applications specific to those instances (for example, the Management Portal for each instance). In addition, the Web Gateway can associate requests for a single application with multiple instances which host the same application code, allowing for load balancing and failover.
The Web Gateway determines the destination instance based on an application access profile. An application access profile defines a relationship between the URL path specified by a request and one or more InterSystems IRIS instances (as represented by their server access profiles). The application access profile also includes other details about how the Web Gateway should handle traffic for that path. See Define an Application Access Profile for Your Web Application Path.
InterSystems recommends that you consider the full process of routing application requests from your web server to the InterSystems IRIS instance which serves your application before you choose the URL paths for which you will define application access profiles. This is especially true if your system features multiple InterSystems IRIS application servers or if your organization has specific URL naming conventions. See Choose the Paths Which Route Requests Through the Web Gateway for guidance.
Secure All Connections
A request passes through two TCP connections on its way from the web client to an InterSystems IRIS application server:
-
The connection between the web client and your web server. To secure the connection between the web client and the web server—that is, to use HTTPS—you must configure SSL/TLS for your web server. Refer to the documentation for your web server for further guidance.
-
The connection between the Web Gateway and the InterSystems IRIS application server. InterSystems supports multiple ways to secure this connection; see Protect Web Gateway Connections to InterSystems IRIS for details.
In addition, you should secure access to the Web Gateway management pages by defining the IP addresses which can access them and by requiring authentication to access them.
Decommission a Web Gateway Connection
If you have uninstalled an InterSystems IRIS instance from your system, you should decommission the Web Gateway connection to that instance by removing all configuration elements related to it. To do so:
-
Delete the Web Gateway application access profiles for any application paths you no longer require. For example, if the instance was named IRISserv1, you would remove the application access profile for the /irisserv1 path (the instance prefix), as well as application access profiles for descendant paths such as /irisserv1/csp.
-
If the instance was serving any applications which you would like to continue serving using other InterSystems IRIS instances, update the Alternative Server fields for the corresponding application access profiles so that they identify the server access profiles for those other instances. (This may involve adding server access profiles for any new InterSystems IRIS application servers.)
-
Delete the Web Gateway server access profile which corresponded to the InterSystems IRIS instance you have uninstalled. Note that you must remove all references to a server access profile from your application access profiles before the Web Gateway allows you to delete a server access profile.
-
Remove web server configuration directives for the paths you no longer require. For example, if the instance was named IRISserv1, you would remove the <Location /irisserv1> block from an Apache web server’s configuration file, along with the <Location> blocks for descendant paths such as /irisserv1/csp. If you chose the automatic web server configuration option when you installed the instance and you are using an Apache web server, comments mark the beginning and end of the configuration directives specific to an instance, as demonstrated in this example.
If you are completely discontinuing use of the Web Gateway by your web server, remove all elements related to the Web Gateway from your web server configuration. Then, delete the Web Gateway files. By default, these files are stored in /opt/webgateway/bin (UNIX®/Linux/macOS) or C:\Inetpub\CSPGateway (Windows).