Access the Management Portal and Other Built–in Web Applications Using Your Web Server
InterSystems IRIS® provides access to several important system utilities—such as the Management Portal—through built-in web applications. If you want to use these web-based utilities, you must connect InterSystems IRIS to a web server through a Web Gateway.
In many cases, the InterSystems IRIS installer can automatically configure a new or upgraded instance to serve its built-in web applications using your web server. If you want to serve your own custom web applications as well, the installer’s automatic procedure provides a basic configuration that you can easily amend to suit your needs. See the section Connect Your Web Server Automatically for details.
If you want to manually set up your web server to route requests for an InterSystems IRIS instance’s built-in web applications, you must follow the same procedure as you would for any other InterSystems IRIS web application. The page Set Up a Web Gateway for Your System provides a general outline for this procedure. On this page, the section Connect Your Web Server Manually provides supplementary guidance specific to these built-in utilities.
This page concludes with instructions for disabling and removing the Private Web Server (PWS), which InterSystems included alongside versions of InterSystems IRIS prior to 2023.2.
The Management Portal URL
The Management Portal is one of the most important web application utilities built into the InterSystems IRIS data platform. Because of its importance and its ubiquity, the Management Portal is the subject of several examples on this page.
When your system is configured as specified on this page, the URL for an instance’s Management Portal home page has the following form, using the <baseURL> for the instance:
https://<baseURL>/csp/sys/UtilHome.csp
For New Installations
If you are installing a new instance of InterSystems IRIS and your system meets the installation conditions for automatic configuration, the installer asks you if you want to configure your web server automatically as part of the installation process. To automatically configure your web server, simply select the option to do so when prompted.
On Windows, the stand-alone Web Gateway installation methods and the Custom setup type do not ask you if you want to configure your web server automatically; these methods perform the automatic configuration silently, by default. If you want to opt out of automatic configuration during a Custom installation, clear the Web Gateway > CSP for IIS installation item.
The automatic procedure configures the web server and the Web Gateway to route requests to your new InterSystems IRIS instance as described in Automatic Configuration Behavior. Review this behavior; under certain circumstances, you must perform some configuration steps manually.
If you complete an installation without automatically configuring your web server and then wish to do so subsequently, use the installer to modify the installation. On Windows, be sure to include the Web Gateway > CSP for IIS installation item. As noted in Automatic Configuration Behavior, in this case you must manually set the CSPSystem credentials for the instance within the Web Gateway’s server access profile for the instance and then restart IIS.
For stand-alone Web Gateway installations, the installer’s automatic configuration procedure can add the Web Gateway module to your web server configuration automatically. However, you must configure connections to your InterSystems IRIS instances and route requests for your web applications manually.
If your system does not meet the installation conditions for automatic configuration, connect your web server manually.
After the installation is complete, restart your web server to ensure that all configuration changes take effect.
For Upgrades
Prior to version 2023.2, all InterSystems IRIS installations included a Private Web Server (PWS), a minimal build of Apache httpd which was configured to handle requests for the instance’s Management Portal and other built-in system web applications.
If you are upgrading from a version of InterSystems IRIS prior to 2023.2 and your system meets the requirements for automatic configuration, the installer provides you the option to automatically configure your instance to connect to a web server which is external to your InterSystems IRIS installation. Simply select the option to do so when prompted.
The automatic procedure adds a Web Gateway to the external web server’s configuration, if it does not already have one. The procedure then defines basic configurations for the external web server and its Web Gateway which enable it to route HTTP requests for the instance’s built-in web applications from a web client to your upgraded instance. This configuration procedure is detailed in Automatic Configuration Behavior. Review this behavior; under certain circumstances, you must perform some configuration steps manually.
Videos which demonstrate how to perform this procedure are available here: https://learning.intersystems.com/course/view.php?id=2333Opens in a new tab
The PWS is not suitable for serving web applications in production, or for use outside of a secured environment. Beginning with version 2023.2, InterSystems stopped installing a PWS with new installations of InterSystems IRIS data platform products (except Community Editions and other evaluation distributions). However, the PWS files remain in place when you upgrade InterSystems IRIS to version 2023.2; you can remove these files manually. Effective with the first EM release of 2026, upgrading any InterSystems IRIS instance will remove all PWS data for the instance.
If you allow the installer to automatically configure an external web server to serve your instance during an upgrade, the automatic procedure disables the PWS. However, it does not uninstall the PWS; the configuration files for the PWS and its corresponding Web Gateway remain in place, and retain any customizations you have made (for example, to configure TLS or serve a custom web application). After upgrading, migrate your custom configurations to the external web server and its Web Gateway and ensure that your web server is successfully serving requests to your instance as desired. Then, you can delete the PWS for that instance.
When you migrate an instance of InterSystems Caché® or InterSystems Ensemble® to InterSystems IRIS on Windows, the conversion process removes the Windows service for the instance’s Apache PWS. If the installer cannot configure IIS during the conversion, the InterSystems IRIS instance will not be connected to a web server and built-in web applications such as the Management Portal will be unavailable.
Migrate Custom Configurations (TLS, Custom Web Apps)
When you upgrade from an instance which uses a Private Web Server and allow the installer to configure the external web server automatically, the installer amends the directives in the external web server’s configuration file and the CSP.ini configuration file for the external web server’s Web Gateway with basic configurations sufficient to serve your instance’s built-in web applications over HTTP. The installer does not copy any configuration parameters from the CSP.ini file for the PWS’s Web Gateway.
Therefore, if you have customized the PWS’s Web Gateway configuration in any way (for example, by creating your own web application or by defining a TLS connection between the PWS’s Web Gateway and the instance) then you must migrate those customizations to your external web server and its Web Gateway manuallyOpens in a new tab.
To migrate custom Web Gateway configurations quickly, you can copy the parameters which correspond to your custom configurations from the CSP.ini for your PWS’s Web Gateway to the CSP.ini for your external web server’s Web Gateway. Then, reload the external web server’s Web Gateway and restart the web server to ensure all configuration changes take effect.
If you have configured an instance which uses a PWS to require TLS for access to its web applications and then allow the installer to automatically configure a Web Gateway connection between your instance and your external web server during an upgrade, you will not be able to access the Management Portal (or other web applications) until you have manually copied the TLS configuration parameters from the instance’s server access profile in the CSP.ini for the PWS’s Web Gateway to the analogous server access profile in the CSP.ini for the external web server’s Web Gateway.
Configure After Upgrade is Already Complete
If you complete an installation without configuring your web server and then wish to do so subsequently, you can still use the installer’s automatic configuration capability by performing the steps which follow. (Alternatively, you can configure a Web Gateway connection between your external web server and your instance manually.)
To use the installer to configure your web server automatically after upgrade is already complete:
-
Run the installer for the later version and navigate through the initial prompts, specifying the name of your upgraded instance as the intended target.
-
On UNIX®, Linux, or macOS: provide details about your installation, as prompted.
-
When the installer asks whether you would like to use the web server to connect to your instance, enter y.
-
Follow the prompts to complete the installation.
-
-
On Windows:
-
When you arrive at the Modify, repair or remove the program dialog, select Modify.
-
When you arrive at the Custom Setup dialog, include the Web Gateway > CSP for IIS installation item.
-
Follow the prompts to complete the installation.
-
Manually specify the CSPSystem credentials for the instance within the Web Gateway’s server access profile for the instance.
-
As noted in the previous sections, you must manually migrate any customizations you have made to the previous web server and its Web Gateway (for example, to configure TLS or serve a custom web application).
Connect Your Web Server Automatically
When Is Automatic Configuration Possible?
If you are installing an InterSystems IRIS instance and you choose a Setup Type that includes the Web Gateway, you can automatically configure your web server to serve requests through a Web Gateway to your instance under the conditions described in the following list. All methods for installing the Web Gateway as a stand-alone component can also configure the web server to include the Web Gateway, provided these conditions apply. However, you must configure the connection to each InterSystems IRIS application server manually.
Automatic web server configuration is possible if:
-
You are using:
-
Apache httpd on UNIX®, Linux, or macOS
-
Microsoft Internet Information Services (IIS) on Microsoft Windows.
-
-
You have already installed the web server within the local file system prior to performing the installation. (Or in the case of IIS, you have enabled it.) For guidance installing Apache on your UNIX® or Linux system, refer to the following Developer Community article: https://community.intersystems.com/post/how-install-apache-iris-supported-operating-systemsOpens in a new tab
Note:On macOS systems, you must have installed a copy of Apache httpd using the Homebrew package manager (https://formulae.brew.sh/formula/httpd#defaultOpens in a new tab). The installer does not support automatic configuration for the Apache httpd installation which is distributed with macOS. For all other platforms, the installer supports the web server provided by the platform.
-
You have installed the web server in its default installation location.
-
The web server is running.
Automatic Configuration Behavior
The installer’s automatic configuration procedure cannot modify the port over which the web server is listening, even when a custom port is specified during installation. Specifying a custom port during installation only modifies the WebServerPort parameter for the InterSystems IRIS instance. In all other cases, the installer assumes that the web server is listening over the default HTTP port, 80 (8080 for macOS).
To access InterSystems IRIS web applications, you must use the port which is specified by your web server configuration.
Except where noted, the installer’s automatic configuration procedure does the following:
-
If the Web Gateway module is not part of your web server configuration, the installer adds it and sets appropriate permissions for the directory which contains the Web Gateway binaries.
-
In the web server configuration, it enables the Web Gateway as the handler for the following relative URL path:
-
/<instanceName>
where <instanceName> is the name of the instance you are installing or upgrading, in all lowercase characters.
Important:If the installer performs the automatic configuration procedure on an Apache web server for an instance which has the same name as an instance which was formerly configured to use the web server, it overwrites any manual edits to the ApacheCSP-SECTION-<instanceName> section which it adds to the configuration file (httpd.conf), restoring the section’s original contents and deleting any customizations. Comments mark the start and end of this section.
-
-
In the web server configuration, it enables the handler for the following relative URL paths:
-
/api
-
/csp
-
/isc
-
/oauth2
-
/ui
Important:Each time the installer performs the automatic configuration procedure on an Apache web server, it overwrites any manual edits to the ApacheCSP-SECTION which it adds to the configuration file (httpd.conf), restoring the section’s original contents. Comments mark the start and end of this section; if you want to customize your Apache configuration, you must do so by adding directives elsewhere in the file.
Note:For Windows systems, you must perform additional IIS configuration to enable a fully functional connection to VS Code (which is facilitated by the instance’s /api/atelier application).
-
-
For Custom installations on UNIX®, Linux, and macOS systems: it updates the port number listed in the Apache web server configuration to the port number you specified in the installation wizard.
-
The installer adds a directive to the web server configuration that redirects requests within the relative path /csp/docbook/ to the corresponding page on the InterSystems documentation site. This is required for links to documentation from within the Management Portal. This is required for links to documentation from within the Management Portal and the InterSystems IRIS launcher (on Windows).
Important:On Windows systems, you must enable IIS’s HTTP Redirection feature for documentation link redirection to work.
-
On RHEL systems with SELinux: it configures appropriate read and write access to the Web Gateway configuration and log files and allows outgoing network connections from the Apache web server.
-
In the Web Gateway configuration, it creates a server access profile for the InterSystems IRIS instance you are installing or upgrading, using the superserver port and the CSPSystem account credentials you specified. This server access profile allows the Web Gateway to connect to your new instance. The server access profile Server Name is the name of the instance, in all lowercase characters.
Note:If you previously installed an instance of InterSystems IRIS 2023.2 without configuring a web server and then allow the installer to run the automatic configuration procedure by running the installer’s modify option, you must set the CSPSystem account credentials for your instance within its server access profile manually. Then, restart IIS.
-
In the Web Gateway configuration, it creates an application access profile for the following relative application path:
-
/<instanceName>
where <instanceName> is the name you specified for the instance you are installing or upgrading, in all lowercase characters.
The application access profile specifies the new server access profile as the default server for all requests sent to this application path.
-
-
In the Web Gateway configuration, it creates application access profiles for the following relative application paths, if they do not already exist:
-
/ (root)
-
/csp
These application access profiles specify the new server access profile as the default server for all requests sent to these application paths.
If these application access profiles already exist within the Web Gateway configuration, the installer updates them so that they specify the new server access profile as the default server for all requests to these application paths.
-
-
It sets the value of the InterSystems IRIS instance’s WebServerPort parameter to 80 (8080 on macOS) and it sets the value of the WebServerURLPrefix to the instance name in all lowercase characters. (If you specify a custom port number during installation, the installer sets the WebServerPort parameter to that number instead.) You can use these parameters to connect an IDEOpens in a new tab to an InterSystems IRIS instance.
Note:If you are installing the Community Edition, you must update the WebServerPort parameter manually to match your web server’s port number.
You must also update the WebServerPort parameter manually if you are upgrading or modifying an existing InterSystems IRIS instance and the instance previously served its web applications using a different port (or did not serve web applications at all).
-
It sets the value of the InterSystems IRIS instance’s WebServer parameter to false (0), preventing the instance from starting its Private Web Server upon instance startup. This change effectively disables the Private Web Server.
Important:If you are installing the Community Edition, the installer does not set the WebServer parameter. You must disable the instance’s Private Web Server manually.
-
On Windows systems, it configures the relevant InterSystems IRIS Server Manager parameters which the InterSystems IRIS launcher requires to construct valid URLs for web application utilities using the launcher—that is, the Management Portal, the class reference, and documentation. You can use these parameters to connect an IDE to an InterSystems IRIS instance. The installer sets the Server Manager’s Web Server Port parameter to 80 (8080 on macOS).
Note:If you are upgrading or modifying an existing InterSystems IRIS instance and the instance previously served its web applications using a different port (or did not serve web applications at all), you must update the Server Manager’s Web Server Port parameter to match your web server’s port number manually.
The automatic configuration procedure ensures that you can access the built-in applications for a specific InterSystems IRIS instance at URLs which include the instance name as a prefix before the application path, in all lowercase characters. You can easily configure the prefix you use to specify an instance.
In addition, the automatic configuration procedure makes built-in applications for the most recently configured InterSystems IRIS instance available at URLs which omit the instance prefix. This means that if only one instance is configured, that instance’s Management Portal is available at the simplified URL<protocol>://<hostname>/csp/sys/UtilHome.csp.
If you have a system with multiple instances configured and you uninstall the most recently configured instance, application access profiles for / (root) and /csp remain associated with the server access profile for the uninstalled instance. To serve requests at those paths, you must manually update the profiles for the / (root) and /csp paths to direct requests to a different default application. You can then remove the obsolete server access profile for that instance.
Automatic Configuration Example
If you installed a single InterSystems IRIS instance named IRISserv1 on a Linux system running Apache httpd, the automatic configuration procedure would add the following directives to the Apache httpd.conf file:
#### BEGIN-ApacheCSP-SECTION ####
LoadModule csp_module_sa "/opt/webgateway/bin/CSPa24.so"
CSPModulePath "/opt/webgateway/bin/"
CSPConfigPath "/opt/webgateway/bin/"
<Location "/csp/">
CSP On
</Location>
<Location "/api/">
CSP On
</Location>
<Location "/oauth2/">
CSP On
</Location>
<Location "/isc/">
CSP On
</Location>
<Location "/ui/">
CSP On
</Location>
<Directory "/opt/webgateway/bin/">
AllowOverride None
Options None
Require all granted
<FilesMatch "\.(log|ini|pid|exe)$">
Require all denied
</FilesMatch>
</Directory>
Redirect /csp/docbook/ http://docs.intersystems.com/irislatest/csp/docbook/
#### END-ApacheCSP-SECTION ####
#### BEGIN-ApacheCSP-SECTION-IRISSERV1 ####
# Note: IRISSERV1 reinstallation or upgrade may replace this section.
<Location /irisserv1>
CSP On
</Location>
Redirect /irisserv1/csp/docbook/ http://docs.intersystems.com/irislatest/csp/docbook/
#### END-ApacheCSP-SECTION-IRISSERV1 ####
The Web Gateway configuration would feature an IRISSERV1 server access profile, and application access profiles for the paths / (root), /csp, and /irisserv1. All three application access profiles would specify IRISSERV1 as the default application server.
As a result of this configuration, the Management Portal home page for IRISserv1 would be available at either http://localhost/irisserv1/csp/sys/UtilHome.csp or the simpler http://localhost/csp/sys/UtilHome.csp.
If you subsequently installed a second InterSystems IRIS instance named IRISserv2 to the same system, the installer would restore the content of the httpd.conf file’s ApacheCSP-SECTION, overwriting any manual changes. It would then append the following directives, after the ApacheCSP-SECTION-IRISSERV1 code block:
#### BEGIN-ApacheCSP-SECTION-IRISSERV2 ####
# Note: IRISSERV2 reinstallation or upgrade may replace this section.
<Location /irisserv2>
CSP On
</Location>
Redirect /irisserv2/csp/docbook/ http://docs.intersystems.com/irislatest/csp/docbook/
#### END-ApacheCSP-SECTION-IRISSERV2 ####
The automatic configuration procedure would add an IRISSERV2 server access profile to the Web Gateway configuration. It would also add an application access profile for the path /irisserv2. The application access profiles for /irisserv2, / (root), and /csp would specify IRISSERV2 as the default application server; the application access profile for the path /irisserv1 would remain unchanged.
As a result of these changes, the Management Portal home page for IRISserv1 would only be available at http://localhost/irisserv1/csp/sys/UtilHome.csp. The Management Portal home page for IRISserv2 would be available at http://localhost/irisserv2/csp/sys/UtilHome.csp or http://localhost/csp/sys/UtilHome.csp.
Connect Your Web Server Manually
The procedure for manually configuring a web server to route requests for the web-based utilities built into InterSystems IRIS (such as the Management Portal) is essentially the same as the procedure for configuring a custom InterSystems IRIS web application. This procedure is outlined in Set Up a Web Gateway for Your System.
This section provides supplemental guidance specific to these built-in applications.
If you are upgrading or re-configuring a version of InterSystems IRIS prior to 2023.2, you can disable and delete the private web server once you have finished configuring your web server to replace it.
Specify the Application Paths You Need
For any InterSystems IRIS system applications you wish to enable, you must do the following:
-
Configure your web server to invoke the Web Gateway to handle all expected requests for the corresponding application path, as well as for any subordinate paths within the application path.
-
Configure a Web Gateway server access profile for your InterSystems IRIS instance
-
Configure a Web Gateway application access profile which specifies that server access profile as the default application server for requests sent to the application path (and subordinate paths).
For a list of the system web applications installed with InterSystems IRIS, see Built-In Applications. InterSystems strongly recommends configuring your web server and Web Gateway to handle requests for all these built-in web utilities. These web applications use endpoints with the following base paths:
-
/api
-
/csp
-
/isc
-
/ui
-
/oauth2
Because a web server configuration and an application access configuration both apply rules of inheritance, the most expedient approach would be to configure requests to these five base paths; this is the approach taken by the installer’s automatic configuration procedure.
If you are serving multiple InterSystems IRIS instances from one Web Gateway and you wish to access built-in utilities for instances independently, you must configure your web server and your Web Gateway so that requests sent to paths which begin with each instance’s CSPConfigName parameter route to that instance. You can configure this parameter for an instance, enabling a custom string to serve as this instance prefix. By default, this parameter is the instance’s name in all lowercase characters. Therefore, the most expedient approach would configure requests to the path /<instanceName> for each instance, where <instanceName> is the instance’s name in all lowercase characters. This is the approach taken by the installer’s automatic configuration procedure.
Route All Necessary Requests for Each Path
You can configure your web server to invoke the Web Gateway to handle all requests sent to a given path, or only requests for files with certain file type extensions.
You can serve the Management Portal by routing requests exclusively for the following file types:
.csp .cls .zen .cxw .jpg .gif .png .svg .css .js
However, REST APIs must support receiving requests at endpoints which do not specify a file (and therefore do not specify a file type). For such applications, it is not possible to invoke the Web Gateway for requests based on the file type, and you must enable the Web Gateway as the handler for all requests at the path level.
Redirect Documentation Links to Documentation Website
When pages within the Management Portal include links to relevant documentation, those links refer to resources within the path <instancePrefix>/csp/docbook for the instance, where <instancePrefix> is the instance name in all lowercase characters. On Windows, the InterSystems IRIS Launcher’s Documentation link also routes to this path.
For these links to function, your web server must redirect requests to this path, sending them to the equivalent URL on the InterSystems documentation web site.
The destination URL for documentation links varies depending on the InterSystems product you are using. To find the correct product identifier for your instance, access any documentation page for the InterSystems product and version you are using and check your browser’s address bar. URLs which specify the latest version of a product (irislatest, healthconnectlatest, and so on) always provide documentation for the most recently released version of the product.
The following sections describe methods to redirect documentation links for Apache httpd and Microsoft IIS. The best method for your system may vary; refer to your web server documentation to explore the options available to you.
Configure Apache to Redirect Documentation Links to Documentation Website
To enable documentation links within an InterSystems IRIS instance if you are using an Apache web server, you must add a Redirect directive to the web server’s configuration which redirects the <instancePrefix>/csp/docbook path for the instance to the analogous URL on the InterSystems documentation website. (By default, <instancePrefix> is the instance name in lowercase characters.)
For example, you can redirect documentation links for a InterSystems IRIS instance named IRISinst2 by adding the following Redirect directive to your web server’s configuration (in the httpd.conf file, or files included therein):
Redirect /irisinst2/csp/docbook/ http://docs.intersystems.com/irislatest/csp/docbook/
Configure Microsoft IIS to Redirect Documentation Links to Documentation Website
To enable documentation links within an InterSystems IRIS instance if you are using a Microsoft IIS web server, you must configure IIS to redirect requests for the instance’s /csp/docbook application to the analogous page on the InterSystems documentation website. To do so, perform the following steps:
-
Ensure that HTTP Redirection for IIS is enabled:
-
Open the Windows Features manager by searching for Turn Windows features on or off or by opening the Control Panel and selecting Programs > Programs and Features > Turn Windows features on or off.
-
Select Internet Information Services > World Wide Web Service > Common HTTP Features > HTTP Redirection, if it is not already selected.
-
Select OK.
Note:When the installer configures an instance’s connection to IIS automatically, IIS redirects documentation links for the instance automatically if HTTP Redirection has been enabled. No further steps are necessary.
-
-
Within the installation directory for your instance, create a /csp/csp/docbook directory.
IIS requires that each application path correspond with a physical path, regardless of whether the web server serves static files. When the installer automatically configures IIS, the path for your InterSystems IRIS instance is mapped to the instance’s /csp directory, and not instance’s base installation directory. If this is the case, create an <installDir>/csp/csp/docbook directory, where <installDir> is the installation directory for your instance. The application will associate requests for /csp/docbook with this directory.
-
In the Connections panel, expand your localhost connection, then Sites, then the application which corresponds with your instance. Within that application, select csp > docbook.
-
On the docbook Home page, select (double-click) HTTP Redirect.
-
On the HTTP Redirect page:
-
For the field captioned Redirect requests to this destination: provide the URL for the online documentation page, appending the string $S$Q (to retain all suffixes and query parameters at the end of the URL). For example:
https://docs.intersystems.com/irislatest/csp/docbook$S$Q
-
Select Redirect all requests to exact destination (instead of relative to destination).
-
-
In the Actions panel, select Apply.
-
Restart IIS for changes to take effect.
Alternatively, you can perform this configuration by creating a /csp/csp/docbook/ directory within your instance’s installation directory. Then, create a web.config file within that directory which contains the following markup:
<?xml version="1.0" encoding="UTF-8">
<configuration>
<system.webServer>
<httpRedirect enabled="true" destination="http://docs.intersystems.com/irislatest/csp/docbook$S$Q" exactDestination="true" />
</system.webServer>
</configuration>
Then, restart IIS to allow this change to take effect.
Windows Only: Update InterSystems IRIS Server Manager
On Windows systems, the InterSystems IRIS launcher uses the server connection details specified within the InterSystems IRIS Server Manager to direct users to the instance’s web-based utilities. To enable the InterSystems IRIS launcher for an instance, modify the server connection details in the InterSystems IRIS Server Manager to match your new web server configuration. See Define a Remote Server Connection.
Windows Only: Configure IIS to Enable VS Code
On Windows systems which use IIS, you must configure IIS to allow VS Code to connect with your InterSystems IRIS instance. The necessary IIS configurations are described in the sections which follow. For detailed instructions on configuring IIS, refer to the IIS documentation (https://learn.microsoft.com/en-us/iis/get-started/introduction-to-iis/iis-web-server-overviewOpens in a new tab).
Disable the WebDAV Module
The IIS WebDAV module (if it is installed) interferes with the Web Gateway when both are enabled to handle communication for an InterSystems IRIS instance’s /api/atelier application. This application provides the connection between the instance and VS Code.
To use VS Code with an InterSystems IRIS instance, you must remove the WebDAV Handler Mapping and disable the WebDAV Module for the relevant path. Depending on your web server configuration, this relevant path may be the instance prefix path, /<instancePrefix>/api, or /<instancePrefix>/api/atelier.
You can perform these configurations using the Internet Information Services Manager, or by editing the applicationHost.config file to include <remove> directives within the <location> directive block for the relevant path ({path}) as in the following example:
<location path="{path}"> <system.webServer> <modules> <remove name="WebDAVModule" /> </modules> <handlers> <remove name="WebDAV" /> </handlers> </system.webServer> </location>
After making changes to the IIS configuration, restart IIS to ensure they take effect.
Enable the WebSockets Feature (for Debugging)
The debugging tool in VS Code requires a WebSockets connection to the InterSystems IRIS instance. Ensure that the IIS WebSocket Protocol feature is enabled by performing the following steps:
-
Open the Windows Features manager by searching for Turn Windows features on or off, or by opening the Control Panel and selecting Programs > Programs and Features > Turn Windows Features on or off.
-
Select Internet Information Services > World Wide Web Service > Application Development Features.
-
Select WebSocket Protocol, if it is not already selected.
-
Select OK.
-
Restart IIS to ensure all changes take effect.
Allow Double Escaping (to Access Certain Packages)
For any file with a name which begins with the % (percent) character followed by two hexadecimal digits (that is, numerals between 0 and 9 or letters between a and f), IIS interprets these first three characters as an encoded hexadecimal character by default. As a result, VS Code cannot view or edit such a file.
If you must view or edit such a file, you must configure IIS Request Filtering to Allow double escaping, either globally or for the specific IIS application location which corresponds with your instance. You can modify this setting by using the IIS Manager or the command line interface (see https://learn.microsoft.com/en-us/iis/manage/configuring-security/configure-request-filtering-in-iisOpens in a new tab) or by setting the attribute allowDoubleEscaping="true" for the appropriate <requestFiltering> element within the IIS configuration file (see https://learn.microsoft.com/en-us/iis/manage/configuring-security/use-request-filteringOpens in a new tab).
For Upgrades from Versions Prior to 2023.2: Disable and Remove the Private Web Server
If you have upgraded to this version of InterSystems IRIS from InterSystems IRIS 2023.2 and you have re-configured your instance to use an external web server, you can disable and (optionally) remove the instance’s private web server (PWS). To do so, perform the following steps:
-
Ensure that:
-
Your external web server and Web Gateway successfully route requests for all desired web applications.
-
Requests to the /csp/docbook application redirect to the documentation web site.
-
On Windows: the InterSystems IRIS Server Manager connection details for the instance match your web server and Web Gateway configuration. (This is necessary to enable the InterSystems IRIS launcher.)
-
-
Prevent the PWS from starting when the instance starts by setting the instance’s WebServer parameter equal to 0. You can edit this parameter within the Management Portal by navigating to System Administration > Configuration > Additional Settings > Startup, or by editing the CPF.ini file directly. (If the installer automatically configured the instance to use the external web server, this step should already be completed.)
-
Restart the instance to stop the PWS. Alternatively, you can stop the PWS without restarting the instance by issuing the following command from the command prompt:
kill `cat <irisInstallDir>/httpd/logs/httpd.pid`
<irisInstallDir>\httpd\bin\httpd -k stop -n <instanceName>httpd
Where <irisInstallDir> is the installation directory for the instance, and <instanceName> is the name of the instance.
Note:If you must re-enable an instance’s PWS for any reason, you can do so by resetting the WebServer parameter to 1 in the CPF.ini file and then restarting the instance. Alternatively, you can start the PWS without restarting the instance by issuing the following command from the command prompt:
<irisInstallDir>/httpd/bin/httpd -d <irisInstallDir>/httpd -c "Listen <port>"
<irisInstallDir>\httpd\bin\httpd -k start -n <instanceName>httpd -c "Listen <port>"
Where <irisInstallDir> is the installation directory for the instance, <instanceName> is the name of the instance, and <port> is the port number for the PWS.
Important:Ensure that you have successfully configured your web server and Web Gateway to route requests for all desired web applications before you irreversibly remove the PWS, as described in the next step.
-
Optional: permanently remove the PWS for the instance by deleting the <irisInstallDir>/httpd/ directory, where <irisInstallDir> is the installation directory for the instance.