Overview

A Profound.js server instance is configured for HTTPS by setting a few options in the instance’s config.js file (see Configuration File). The simplest configuration uses only sslKey and sslCert to point at the private key and certificate; more advanced setups can use sslOptions to pass any option supported by the Node.js HTTPS module.

The certificate and key files must be readable by the user profile the instance runs under – on IBM i that is normally PROFOUNDJS. Restart the instance after changing any of these settings.

How the Options Interact

sslKey and sslCert - Paths to the PEM private key and certificate. When these are set and securePort is not set, the instance serves HTTPS on port and does not serve HTTP at all.
securePort - Adds a separate HTTPS listener. HTTP is served on port and HTTPS on securePort. The instance will not start unless sslOptions, or both sslCert and sslKey, are also configured.
redirectHTTP - Sends a 301 redirect from the HTTP listener to the HTTPS listener and sets a Strict-Transport-Security header. The instance will not start if this is set to true without securePort.

Example 1: HTTPS Only

Use this when the instance should be reachable over HTTPS and nothing else. Because securePort is omitted, the value of port becomes the HTTPS port – here the standard HTTPS port 443.

Configuration for HTTPS only

module.exports = {
  // With sslKey/sslCert set and no securePort, this port serves HTTPS
  "port": 443,
  "staticFilesDirectory": "htdocs",
  "pathlist": [
    "pjssamples"
  ],
  "initialModules": {
    "/hello": "pjssamples/hello",
    "/connect4": "pjssamples/connect4"
  },
  "timeout": 3600,
  // Absolute IFS paths to the PEM private key and certificate
  "sslKey": "/my_cert/key.pem",
  "sslCert": "/my_cert/cert.pem"
}

Example 2: HTTP and HTTPS Together

Use this while migrating to HTTPS, when some clients still need plain HTTP. Adding securePort starts a second listener, so the instance answers HTTP on port 80 and HTTPS on port 443.

Configuration for both HTTP and HTTPS

module.exports = {
  // HTTP listener
  "port": 80,
  "staticFilesDirectory": "htdocs",
  "pathlist": [
    "pjssamples"
  ],
  "initialModules": {
    "/hello": "pjssamples/hello",
    "/connect4": "pjssamples/connect4"
  },
  "timeout": 3600,
  "sslKey": "/my_cert/key.pem",
  "sslCert": "/my_cert/cert.pem",
  // Separate HTTPS listener; requires sslKey + sslCert (or sslOptions)
  "securePort": 443
}

Example 3: Redirect All HTTP Traffic to HTTPS

This is the recommended production configuration. The HTTP listener stays open only long enough to redirect: any request that arrives over HTTP is answered with a 301 redirect to the same URL on the HTTPS port, and a Strict-Transport-Security header tells the browser to use HTTPS on subsequent visits.

Configuration to redirect HTTP to HTTPS

module.exports = {
  // HTTP listener - only used to redirect clients to HTTPS
  "port": 80,
  "staticFilesDirectory": "htdocs",
  "pathlist": [
    "pjssamples"
  ],
  "initialModules": {
    "/hello": "pjssamples/hello",
    "/connect4": "pjssamples/connect4"
  },
  "timeout": 3600,
  "sslKey": "/my_cert/key.pem",
  "sslCert": "/my_cert/cert.pem",
  "securePort": 443,
  // 301-redirect every HTTP request to https://<host>:<securePort>
  "redirectHTTP": true
}

Troubleshooting

securePort was specified but sslOptions or sslCert and sslKey must also be configured - securePort is set without a certificate. Add sslKey and sslCert, or sslOptions;
redirectHTTP is “true” but securePort isn’t set - redirectHTTP only applies when there is a separate HTTPS listener. Add securePort, or remove redirectHTTP;
The instance starts but the browser cannot connect - On IBM i, confirm no other server is already bound to the port, and confirm the instance job is active in the PROFOUNDJS subsystem.

Configuring HTTPS/SSL