Nginx for UNIX®/Linux/macOS

This page describes how to build and configure an Nginx web server for use with the InterSystems Web Gateway on UNIX®, Linux, or macOS.

Nginx is an Open Source product and the source code can be downloaded free of charge from: http://nginx.org/Opens in a new tab

Some prebuilt kits are available for Linux which are, generally, a few builds behind the latest Nginx build. However, given that extensions must be compiled into the Nginx core, it is necessary to build the web server locally from the source code in order to include support for CSP.

After the steps in this page, you can use the Web Gateway management pages to further configure the Web Gateway.

This page assumes that:

• CSP/Web Gateway web server components are installed in /opt/webgateway/bin/

• InterSystems IRIS, if installed locally, is in /opt/iris/

• The web server is installed under /opt/nginx/

If the layout is different on your system, modify the configuration directives as appropriate.

The Web Gateway components and the CSP static files should be installed as follows:

1. Web Gateway Network Service Daemon (NSD)

   • CSPnsd

   The default location for this binary is /opt/webgateway/bin/

2. HyperEvents Components

   CSPBroker.js

   CSPxmlhttp.js

   The default location for these files is /opt/iris/csp/broker

   If these files are to be served as static components directly by the web server, copy them to /opt/nginx/html/csp/broker

3. Miscellaneous static resources used by the Management Portal

   A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is /opt/iris/csp/sys

   If these files are to be served as static components directly by the web server, copy them to /opt/nginx/html/csp/sys

Most of the Web Gateway functionality is provided by the NSD (CSPnsd). For CSP access, Nginx can be built and configured to communicate with the NSD through a small compiled-in module, ngx_http_csp_module.c. For convenience, all Web Gateway installations include this source file.

The build instructions given here are based on the official documentation for building Nginx under UNIX® systems:

http://nginx.org/en/docs/configure.htmlOpens in a new tab

The Nginx documentation stipulates that the following third party add-ons are also required:

• PCRE

  http://www.pcre.org/Opens in a new tab

• OpenSSL (for SSL/TLS)

  https://www.openssl.org/Opens in a new tab

• Zlib

  http://zlib.net/Opens in a new tab

However, it is possible to create a fully functional server without these components, provided the final installation doesn’t require the functionality that would otherwise be provided by them.

A typical configuration script for building Nginx, including all optional modules listed above, is as follows:

./configure --prefix=/opt/nginx --with-http_ssl_module

This results in a default Nginx build installed under: /opt/nginx

The build process can be modified to exclude optional modules:

• OpenSSL - Remove SSL/TLS capability:

  Remove directive: --with-http_ssl_module

• Zlib - Remove GZIP capability:

  Add directive: --without-http_gzip_module

• PCRE - Remove HTTP rewrite capability:

  Add directive: --without-http_rewrite_module

You must configure the web server so that it recognizes requests your InterSystems IRIS application must serve and then passes those requests to the NSD.

To do so, edit the web server configuration file (nginx.conf) which is found in /opt/nginx/conf

This section describes the server configuration directives which the CSP extension module provides for configuring the web server. Issuing any of these directives within the context of a location block applies the directive to traffic at the path specified.

location /demo/app {
  CSPFileTypes csp cls;
}

Example: Enable CSP Routing for All Traffic at a Particular Path

Place the following section within the appropriate server configuration block to route all traffic sent to the /csp path to the Web Gateway:

location /csp {
CSP On;
CSPNSD_pass localhost:7038;
}

Example: Route Requests for InterSystems IRIS File Types to the Web Gateway

Place the following section within the appropriate server configuration block to enable CSP routing for requests sent to the /csp path for the InterSystems IRIS file types (.csp, .cls, .zen, and .cxw) as well as file types required to serve static elements of the Management Portal interface:

location /csp {
CSPFileTypes  csp cls zen cxw .jpg .gif .png .svg .css .js;
CSPNSD_pass localhost:7038;
}

To use VS Code with the InterSystems ObjectScript extensionsOpens in a new tab (or any IDE which uses the /api/atelier web application) as an ObjectScript IDE, you must perform the following additional modifications to your Nginx configuration:

1. The /api/atelier web application uses HTTP headers which include underscores. By default, Nginx’s underscores_in_headers directive instructs Nginx to silently drop these headers. You must configure your Nginx server to include them. See http://nginx.org/en/docs/http/ngx_http_core_module.html#underscores_in_headersOpens in a new tab.

2. Features such as the debugger require a WebSocket connection. By default, Nginx is not configured to support WebSockets. For information on enabling WebSockets, refer to the Nginx documentation: (http://nginx.org/en/docs/http/websocket.htmlOpens in a new tab).

To start Nginx:

/opt/nginx/sbin/nginx

To stop Nginx:

/opt/nginx/sbin/nginx –s stop

See Operating the NSD for instructions on how to operate the NSD.

Nginx can be built to work with the dynamically-linked Universal Modules CSPx.so (runtime) and CSPxSys.so (Web Gateway systems management). The procedure for building and configuring Nginx to work with the Universal Modules varies from the NSD-based deployment as follows:

• In step 3, copy the module source code ngx_http_csp_module_sa.c, cspapi.h, and ngx_http_csp_common.h to the specified directory, instead of ngx_http_csp_module.c.

• In step 4, the configuration file for CSP (/opt/nginx-n.n.n/csp/config) should read as follows:

  ngx_addon_name=ngx_http_csp_module_sa
  HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module_sa"
  NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module_sa.c"
  

  

• Add the CSPModulePath directive from the http configuration block to specify the path to the Universal Gateway Modules.

  CSPModulePath /opt/webgateway/bin;
  

  

• The following directives are not supported:

  • CSPNSD_pass

  • CSPNSD_response_headers_maxsize

  • CSPNSD_connect_timeout

  • CSPNSD_send_timeout

  • CSPNSD_read_timeout

• The following directives are supported:

  • CSP

  • CSPFileTypes