Skip to main content

The Web Gateway: Serve InterSystems Web Applications and REST APIs to a Web Client

An InterSystems IRIS® web application consists of code which provides content dynamically to a web client (usually a web browser) in response to a request. The InterSystems Web Gateway makes this possible: it is a software utility that mediates the connection between your web server and the InterSystems IRIS instance or instances which host your web application code. The Web Gateway supports HTTP, HTTPS, and WebSocket protocols, and it provides capabilities such as load balancing and failover for your application traffic.

The Web Gateway:

  • extends the functionality of your web server so that the web server can recognize and handle requests for InterSystems web applications.

  • manages server access profiles to connect with the application server processes within each of your InterSystems IRIS instances.

  • routes a request for an application to the InterSystems IRIS instance which hosts the application, based on application access profiles between certain request paths and certain InterSystems IRIS application servers.


The process within an InterSystems IRIS instance which invokes application code in response to incoming requests is sometimes referred to as the CSP Server or CSP Engine, in reference to the legacy InterSystems web application framework. However, this process responds to requests for all InterSystems IRIS web applications—not merely CSP applications. For this reason, the Web Gateway documentation uses the term “application server” when it is necessary to refer to this process specifically. Elsewhere, the documentation treats the entire InterSystems IRIS instance as the effective target of a Web Gateway connection.

Web applications provide access to several important InterSystems IRIS system utilities, such as the Management Portal. To use these, you must connect InterSystems IRIS to a web server through a Web Gateway. See Serve the Management Portal (and Other System Applications) Using Your Web Server.

How the Web Gateway Routes InterSystems Web Application Requests

The following diagram visualizes the way a request for a web application travels from a client (such as a web browser) to an InterSystems IRIS instance where the web application is running.

request traveling from client to Web Gateway to application server

The process can be summarized as follows:

  1. The client sends a request to a certain URL path. In the example, the client sends an HTTP GET request to

  2. The web server receives the request and checks its configuration to determine whether it should invoke the Web Gateway for that request. The diagram demonstrates this with an excerpt from the configuration file for a hypothetical Apache web server. In the example, the web server configuration instructs the web server to invoke the Web Gateway to handle any request within the /criticalapp path.

  3. The Web Gateway checks its configuration to determine which InterSystems IRIS application server should receive the request. The diagram demonstrates this with excerpts from the Web Gateway’s hypothetical CSP.ini configuration file. In our example, the application access profile for the /criticalapp path instructs the Web Gateway to route requests within that path to the application server process for the InterSystems IRIS instance iris1 by default, or (if iris1 is unavailable) to the alternative application server for the instance iris2.

  4. The Web Gateway transmits the request over a secured TCP connection to the host and superserver port for the appropriate application server. As presented in the diagram, the Web Gateway stores these connection details in a server access profile for each application server. In the example, iris1 is currently offline, so the Web Gateway sends the request to the alternative server iris2.

  5. The application server process for the InterSystems IRIS instance calls the appropriate application code based on the settings for the web application within the InterSystems IRIS instance. The application code produces a response.

  6. The response travels back through the Web Gateway to the web server. The web server transmits the response to the client.

Structure of an InterSystems Web Application URL

The Web Gateway allows you to serve InterSystems IRIS web applications at URLs which follow the following format:


An InterSystems IRIS instance usually hosts multiple web applications. The URLs for all the web applications which are hosted by an instance share in common the base URL for the instance. The base URL is the following portion of an InterSystems web application URL:


The following table describes each part of these URLs.

URL Part Description

http or https, depending on whether or not you have configured your web server to use TLS. InterSystems strongly recommends the use of TLS.


The IP address or DNS name where your web server is available. When the web server is on the same machine as the client, this is usually localhost.


The port number over which your web server is listening for requests. You do not need to specify a port number unless your web server is listening for requests on a port other than the standard ports for HTTP (80) or HTTPS (443).


A string which uniquely identifies one of your InterSystems IRIS application servers.

If you do not need to discriminate between multiple InterSystems IRIS instances, you can configure the Web Gateway to serve web applications at URLs which omit this portion of the path, as in the preceding example. However, if you serve multiple InterSystems IRIS instances using a single web server and you must access a web application unique to one instance (such as an instance’s Management Portal), you must configure your web server and Web Gateway to route requests to the instance using this identifier as a prefix to the application path. This identifier is the CSPConfigName for the instance. By default, an instance’s CSPConfigName is its instance name, in all lowercase characters. However, it can be configured.

If the application in the preceding example were exclusively available on the InterSystems IRIS application server named iris2, then you could configure the /iris2 path within the web server and Web Gateway configurations to serve the application at the following URL:

[appPath] The relative path unique to the application within each InterSystems IRIS application server. When you define an application within an InterSystems IRIS application server, this is the application’s Name.
[fileOrQuery] Optional. Any combination of subordinate path, file name, and query parameters which the application may use to process the request.

The instancePrefix identifier is not available when an InterSystems IRIS instance is running within a container. To access to the Management Portal and other built-in web applications for a specific instance in a multi-instance cluster, you must deploy a dedicated Web Gateway container for each InterSystems IRIS container. The specific procedure depends on the manner of deployment. For more information on this topic, see Web Access Using the Web Gateway Container.

Set Up a Web Gateway for Your System

You can set up a Web Gateway connection in several ways. As the preceding diagram suggests, you can deploy the Web Gateway alongside your web server on a separate machine, remote from your clients and your InterSystems IRIS instances. Alternatively, the web client, web server, and Web Gateway can all reside on the same machine. You can install the Web Gateway on-premises; alternatively, you can deploy a webgateway container from a Docker image available in the InterSystems Container RegistryOpens in a new tab. Each of these webgateway container images contain a web server (Apache or nginx) which is pre-configured with the Web Gateway extension.

Set Up a Web Gateway for Your System provides an overview of the entire setup process, regardless of your use case.

Manage a Web Gateway Connection

Regardless of how you deploy the Web Gateway, it provides a standard set of interfaces for managing connections between web clients and the InterSystems IRIS instances which host your web applications.

The Web Gateway management pages provide a graphic user interface for configuring default parameters, defining connections to your InterSystems IRIS instances, monitoring and testing those connections, defining routing behavior for your applications, and more. Web Gateway configuration information is stored in the CSP.ini file. In the majority of cases, InterSystems recommends the use of the Web Gateway management pages or Web Gateway Registry methods to configure the Web Gateway. However, for containerized deployments, you can automate and synchronize the configuration of one or more webgateway containers upon deployment by modifying CSP.ini files directly using the CSP.ini merge feature.

The InterSystems IRIS Web Gateway Registry enables an InterSystems IRIS instance to monitor and manage its connection to the Web Gateway programmatically. All web server installations and Web Gateway installations are registered with InterSystems IRIS as they connect. Using the Gateway Registry, InterSystems IRIS code can interact with the Web Gateways to which the instance is connected, enabling it to read and write configuration details, monitor the system status, and audit the Web Gateway Event Log.

FeedbackOpens in a new tab