Using Web Applications with a Remote Web Server

Configuring the Web Server and Web Gateway

This section discusses how to set up a web server and the Web Gateway to provide access to a web application installed on a remote InterSystems IRIS server. The instructions refer to the web server as Machine W and to the computer running InterSystems IRIS® as Machine I. The setup includes the following procedures:

Install the Web Gateway on the Web Server Machine

Install the Web Gateway on the web server machine, Machine W, where IIS or Apache is running. See Installing the Web Gateway Only in the Installation Guide if you need more detailed information. During the installation process, follow these instructions:

In the Setup Type dialog box, select Web Server and select Next.
Review the installation name, type, and destination directory and, if correct, select Install.

This installation process creates the CSP directory structure on the web server, Machine W and creates virtual directory references for the /CSP and /CSP/Bin files.

Configure the Web Gateway

Next, adjust the Web Gateway configuration on the web server, Machine W. Although this configuration information is stored in the configuration file, always use the Web Gateway management pages to update the configuration:

Navigate to the Web Gateway management pages main menu by pointing a browser to:
http://localhost/csp/bin/Systems/Module.cxw
(Bookmarking this URL is helpful). This link is for your external web server, not the Private Web Server supplied with InterSystems IRIS.
Note that the link above is correct if you are on the same system that the web server is running on using port 80. If you are trying to access the management pages from a remote system, you are denied access by default. You can configure the web server to allow remote access through the Web Gateway management pages Default Parameters page. Set the System Manager Machine/s field to the IP address of the remote system. This field accepts a comma- or plus-separated list of IP address of machines that can access the Web Gateway management pages.
For additional information, see Enabling Access from Additional Client Addresses.
Select Server Access in the left-hand menu. If IRIS is installed on the web server, the InterSystems IRIS installation configures a LOCAL web server to connect to the InterSystems IRIS instance on the local machine, Machine W.
Create a new server to represent the InterSystems IRIS instance running on the remote machine, Machine I:
1. Select Add Server.
2. Enter a name for the server (Machine I for example).
3. Enter the IP Address and Superserver TCP Port of the remote InterSystems IRIS server running on Machine I.
4. Modify the Connection Security settings to match the level of authentication expected by Machine I for Web Gateway connections. See Web Gateway and Security for details.
5. Select Save Configuration.
For additional information, see Adding a Server Configuration.
Select Application Access in the left-hand menu to associate the path to the web application on the remote InterSystems IRIS server, Machine I, with the server configuration previously created for Machine I. The default paths are predefined for / and /csp.
Create a new application path to represent the web application running on the remote machine, Machine I. You can either copy an existing configuration (such as /csp) or select Add Application to manually create a new path configuration. The path you create for the application must match that defined for the application in the InterSystems IRIS instance on Machine I.
For example, the default path to the Management Portal is /csp/sys. If you are creating a new application, choose your own path name. For example: /myapp or /csp/myapp. Having created the new path, modify the Server 0 parameter for the path such that it takes the value of the InterSystems IRIS server configuration that you previously set up for Machine I.
Finally, save the new path configuration.
For additional information, see Adding an Application Path.

If Serving Static Files from the Web Server

If you are planning to serve static files from the web server, create directories on Machine W to represent your application path. These directories exist solely to hold static content such as image files. You do not have to place any CSP files here; they reside on Machine I.

Under the directory install-dir\CSP on Machine W, create \Samples and \User directories. Also create directories to represent other paths which may contain static components referenced in CSP pages. The example in the previous section requires you to create a directory for \myapp.

Configure Web Server Paths

The application paths in the previous steps correspond to requests for CSP pages in the equivalent locations. For example:

http://domain.com/myapp/login.csp
http://domain.com/csp/myapp/login.csp
http://domain.com/csp/sys/login.csp

Inheritance is applied in a hierarchical fashion. Consider the following request:

http://domain.com/csp/newapp/login.csp

The application path configuration for /csp/newapp is used if it exists. If not, the configuration defined for /csp is used instead.

The Web Gateway installation procedures configure the hosting web server to recognize the /csp virtual path. Typically, these same settings also apply to directories placed under /csp (/csp/myapp, for example).

If you create a new path (such as in the first example, /myapp), you must configure the web server to recognize this new virtual path. These procedures are different depending on the web server you use. Follow the procedures in that applies to your web server:

Add Virtual Directories to IIS

The installation procedure for the Web Gateway configures the virtual directory install-dir\csp for web applications. If all of your applications are under this virtual directory (for example, install-dir\csp\myapp) and you are not using virtual hosts, you do not need to add virtual directories. The instructions in this section apply specifically to the IIS (Internet Information Services) web server version 7 or later.

Set up the application path resembling /myapp in the previous examples with properties similar to the /csp virtual directory which is automatically created for you during the Web Gateway installation.

Navigate to the Internet Information Services management dialog box, which is likely accessible from the Administrative Tools menu of the Windows Control Panel.
Expand the folders and right-click Default Web Site.
Point to New and select Virtual Directory to create a new directory record with the following values:
```
Alias:                 myapp
Directory:             C:\iris\csp\myapp
```
Either select Save and Apply all changes, or if you are using the wizard, select Finish.

Restart IIS to apply the changes.

Add Aliases to Apache Configurations

If you are using an Apache web server to control a remote InterSystems IRIS server and your application path is altered from the /csp default, you must manually add a corresponding alias to the Apache configuration file pointing to the local CSP directory.

For example, to remotely serve the web applications on the InterSystems IRIS instance iris on Machine I from the application path defined on the web server, /myapp/csp, add the following alias line to the httpd.conf file on Machine W:

Alias /myapp/csp "C:/iris/CSP"

Restart the Apache web server to apply the changes.

Accessing CSP on Multiple InterSystems IRIS Servers

Read this section if you need to configure a single web server to access one or more web applications on multiple InterSystems IRIS servers. This section uses the Management Portal as the example application. Adapt these procedures for your own web application. The Management Portal application is usually called with a URL in this format:

http://domain.com/csp/sys/UtilHome.csp

For additional information, see Define a Remote Server Connection in System Administration Guide.

Configuring the InterSystems IRIS Server for the Application Path

If you are content with using the InterSystems IRIS server name in the web application URL, follow this procedure. If you do not want the InterSystems IRIS server name displayed in the URL, then follow the procedure in the following section Changing the InterSystems IRIS Server Name in the URL.

On your web server, access the Web Gateway management pages main menu with:
```
http://localhost:<port_no>/csp/bin/Systems/Module.cxw
```
Select Server Access. Add server configurations for iris1 and iris2. See Configuring Server Access for details.
Select Application Access. Create an application path /iris1/csp/sys/ with a Default Server of iris1. Create an application path /iris2/csp/sys/ with a Default Server of iris2. See Configuring Application Access for details.
If the web server is IIS, then set up virtual directories for /iris1 and /iris2 as described in Add Virtual Directories to IIS.
If using an Apache web server, see Add Aliases to Apache Configurations.

To access the Management Portal on InterSystems IRIS servers iris1 and iris2, include the server name as part of the URL as follows:

http://domain.com/iris1/csp/sys/UtilHome.csp
http://domain.com/iris2/csp/sys/UtilHome.csp

Changing the InterSystems IRIS Server Name in the URL

If you do not want the InterSystems IRIS server name displayed in the web application URL, then follow the procedure in this section to create a substitute name.

Use the CSPConfigName parameter of the %System.CSP.SetConfigOpens in a new tab method for each server. This example uses linda as the substitute name for server iris1 and perry as the substitute name for a server iris2. You would use your own server and substitute names.

In an ObjectScript shell on the iris1 server, run:

d $System.CSP.SetConfig("CSPConfigName","linda")

In an ObjectScript shell on the iris2 server, run:

d $System.CSP.SetConfig("CSPConfigName","perry")

Then, complete the following steps:

On the web server, access the Web Gateway management pages main menu with:
http://localhost/csp/bin/Systems/Module.cxw
Select Server Access. Add server configurations for iris1 and iris2. See Configuring Server Access for details.
Select Application Access. Create an application path /linda/csp/sys/ with a Default Server of iris1. Create an application path /perry/csp/sys/ with a Default Server of iris2. See Configuring Application Access for details.
If the web server is IIS, then set up virtual directories for /iris1 and /iris2 as described in Add Virtual Directories to IIS.
If using an Apache web server, see Add Aliases to Apache Configurations.

CSPConfigName also accepts a comma delineated list for CSP configuration names. This allows you to have multiple configuration names instead of a single value. For example:

d $System.CSP.SetConfig("CSPConfigName","linda,linda1,linda2,linda3")

To see other CSP global parameters, enter %SYS>d $system.CSP.DisplayConfig(). If you have set CSPConfigName, you may want to also set WebServerURLPrefix so that Studio uses the same URL construction. See WebServerURLPrefix.

Configuring Apache Virtual Hosts

An alternative method for accessing an application on multiple servers is to use virtual host arrangements. Virtual hosts are a common feature in Apache web server configurations and are straightforward to set up in this server environment. For example, consider two virtual hosts, each listening on a separate TCP port:

http://virtual_host1:81/csp/sys/UtilHome.csp
http://virtual_host2:82/csp/sys/UtilHome.csp

Both virtual_host1 and virtual_host2 are served by the same web server and Web Gateway.

The following shows the Apache configuration (httpd.conf) for this arrangement:

<VirtualHost virtual_host1:81>
   ServerName virtual_host1
</VirtualHost>

<VirtualHost virtual_host2:82>
   ServerName virtual_host2
</VirtualHost>

Configure the use of these virtual hosts as follows:

Navigate to the Web Gateway management pages main menu by pointing a browser to:
http://localhost/csp/bin/Systems/Module.cxw
Select Server Access to create a server configuration for iris1 and iris2.
Select Application Access to create the application paths //virtual_host1/csp/sys/ and //virtual_host2/csp/sys/.
Note the use of the double forward-slash (//) to introduce the virtual host name.
Set the Server 0 for path //virtual_host1/csp/sys/ to be the name of the server configuration set up for iris1 in the previous step.
Set the Server 0 for path //virtual_host2/csp/sys/ to be the name of the server configuration set up for iris2 in the previous step.
No changes are required in the configuration of the two remote InterSystems IRIS servers. The application path for the portal remains as /csp/sys/ in both cases.

See Virtual Hosts Overview for more information.

Virtual Hosts Overview

Virtual hosts are a means through which you can transparently serve applications on one or more instances through a common web server. Each server installation appears to operate as a separate web server.

The differentiating factor in virtual host setups can be one of the following:

Web server IP address — The server hosting the web server is exposed through two IP addresses. For example:
```
123.123.123.1 == www.serverA.com
123.123.123.2 == www.serverB.com
```
Web server port — This method is useful for testing different configurations, though it involves including the port number in the request for cases where non-standard TCP ports are used (TCP ports other than 80). For example:
```
Web Server TCP Port 80 == www.serverA.com
Web Server TCP Port 81 == www.serverB.com
```
Path — the preferred way of implementing virtual hosts. You register the two names and they translate to a single physical IP address for the web server. For example:
```
www.serverA.com == 123.123.123.1
www.serverB.com == 123.123.123.1
```

Regardless of which way you choose, set up a named slot for each InterSystems IRIS installation in the Web Gateway configuration (it does not need to be the same as the InterSystems IRIS instance name). The superserver port that the Web Gateway configuration (for each server) is pointing to is what is important.

For example:

www.serverA.com 
www.serverB.com

Both are served by a single web server installation.

You can implement servers including mixtures of all three. Options 1 and 3 are identical from the browser perspective. You can configure each virtual host to have its own documents root, etc.

To extend the virtual host concept through to CSP, suppose you wish to run the same web application through two virtual hosts, but on different InterSystems IRIS instances. For example, one site for testing and another for production.

www.serverA.com/csp/login.csp ==> irisA
www.serverB.com/csp/login.csp ==> irisB

A web application’s access to an InterSystems IRIS server is controlled through the Web Gateway Application Access configuration option. Typically, the following two entries are defined:

/ 
/csp

The name of the InterSystems IRIS server is associated with these application path definitions:

/ (Default Server == irisA) 
/csp (Default Server == irisA)

The Web Gateway allows you to extend this configuration to include the name of a virtual host through which you access the application.

/ (Default Server == irisA) 
/csp (Default Server == irisA) 
//www.serverA.com/csp (Default Server == irisA) 
//www.serverB.com/csp (Default Server == irisB)

You can then configure a separate InterSystems IRIS server for www.serverA.com/csp and www.serverB.com/csp as shown above. Introduce server names by //, as shown.

The current rules of inheritance apply. For example, if you request www.serverA.com/xxx/yyy.csp, then the InterSystems IRIS server defined for / is ultimately used, unless, you define an ultimate default for serverA as shown below:

/ (Default Server == irisL) 
/csp (Default Server == irisL) 
//www.serverA.com/ (Default Server == irisL) 
//www.serverA.com/csp (Default Server == irisA) 
//www.serverB.com/csp (Default Server == irisB)

Note:

The servers specified in the Web Gateway configuration do not necessarily have to be virtual. For example, you can configure a single NSD installation to support several real Apache installations with a different set of InterSystems IRIS servers defined for each one. Further, you can configure each Apache server to support many virtual hosts.

The Web Gateway identifies the host for the application through the CGI environment variable SERVER_NAME.

IIS Technical Notes