Overview

The installation/upgrade process has two main steps:

1. Starting the Installation Process by installing the profoundjs package using Node Package Manager (NPM).
2. Completing the Installation Process by running the complete_install.js script.

Starting the Installation Process

The installation process is initiated from a shell command line.

On IBM i, this is done using a PASE shell (not QShell). The best way to use a PASE shell is to connect to your IBM i server via SSH using a Unix-style terminal emulator, such as PuTTY or Git Bash for Windows. This provides a friendlier interface for working with Node.js and other Unix-style commands on the command line. For more information on configuring SSH, follow this link: https://wiki.midrange.com/index.php/SSH. Alternatively, you can start a PASE shell from a TN5250 session by running the command CALL QP2TERM.

Once you are on a shell command line, there are a few simple commands that will start the installation.

To begin, you must first create a directory in which you want to install Profound.js. You will use the mkdir command to do so. In the example below, a directory named profoundjs is created at the root of the file system.

If installing on IBM i and you'd like to install the IFS components onto an IASP, create the installation directory in the IASP directory on the IFS. For example: /MY_IASP_NAME/profoundjs

The next step is to enter the directory (using the cd command) and run the Node Package Manager (npm) install process for Profound.js using the command npm install profoundjs@next. This will download all package dependencies and install the product.

cd /
mkdir profoundjs
cd profoundjs
npm install profoundjs@next

 Warning Messages

Profound.js is provided as an npm package hosted on npmjs.com. When installing npm packages into a directory that does not have a package.json file to describe your project, npm produces several warning messages that look like this:

These warning messages do not mean that the installation failed. They simply mean you did not have a package.json file to descibe your project.

If a package.json is not found, the Profound.js installation will create a default package.json file in your installation directory for you. You can then maintain this file to keep track of your project's version, description, other npm dependencies, and more. For more information about the npm package.json file, click here.

Completing the Installation Process

An additional step is required to complete the installation. Run this command from within your installation directory:

node complete_install.js

For a new installation (when config.js file is not present in the installation directory), the complete_install.js script will prompt you for details on how to set up the Profound.js installation. Default options are shown in parentheses after each prompt; so if the default is appropriate, you can just press Enter. The prompts are shown below:

• Specify port number for Profound.js server (8081):
  This specifies the port number Profound.js will run from.
  
  

• Install with Git integration (y)?
  Answer 'y' to install necessary components for Git integration features. This question only appears on supported platforms. Currently, Git integration is only supported on Windows, Linux, and Mac.

• Install Profound.js Connector IBM i ILE components (y)?
  If you are installing on IBM i, you will have the option of installing the Profound.js Connector, which allows native IBM i applications to interface with Profound.js. You can press Enter here to proceed, or type 'n' and press Enter if you don't want to install the Connector.

• Enter Profound.js Connector library name (PROFOUNDJS)?
  Specify the IBM i library name where the Profound.js Connector will be installed. You can press Enter to accept the default name of PROFOUNDJS or type in a different name.
  
  

• Enter Profound.js Connector library IASP (*SYSBAS)?
  Specify an IASP name to install the Profound.js Connector library onto an IASP. Use the default, *SYSBAS, if you do not want to install onto an IASP.

• Control server instance using STRTCPSVR/ENDTCPSVR commands (y)?
  Press Enter to configure the Profound.js server instance to start/end using the STRTCPSVR/ENDTCPSVR commands. Otherwise the instance will have to be started manually by running commands from a PASE shell.

• Server instance name (PROFOUNDJS)?
  This question appears if you select 'y' above. Press Enter to accept the default name, or type an alternate name. The name entered here controls the job name for the server instance which will run in the PROFOUNDJS subsystem. The server instance name also controls the name of the instance configuration directory, which will be:

/profoundjs-base/instances/INSTANCE_NAME

• Specify CCSID for instance INSTANCE_NAME (37):
  Press Enter to run the server instance with CCSID 37 or type an alternate CCSID. You should specify the same EBCDIC CCSID that you use with your IBM i applications.
  
  
• Specify Node.js path for instance
  This question allows you to specify an alternate Node.js binary path for the instance. The default value is the path of the Node.js binary used to run the installation process. Values such as these can be used to select alternate Node.js versions:
  • /QOpenSys/pkgs/bin/node (IBM i system default Node version)
  • /QOpenSys/pkgs/lib/nodejs14/bin/node (Node.js 14)
  • /QOpenSys/pkgs/lib/nodejs16/bin/node (Node.js 16)
    
    

• Autostart server instance when TCP/IP starts (y)?
  Press Enter to configure the server instance to autostart when TCP/IP starts, or type 'n' and press Enter if you don't want to autostart the instance.
  
  

• Integrate with separate Profound UI instance (n)?
  Press Enter to continue without configuring integration with Profound UI, or type 'y' and press Enter to configure Profound UI integration.
  
  
• Profound UI instance name (PROFOUNDUI)?
  This question only appears if you answered 'y' to the above question. Enter a Profound UI instance name to integrate with. This will set the configuration settings staticFilesDirectory and profounduiLibrary to the Profound UI instance's document root directory and installation library.
  
  

For an upgrade installation (config.js file is present), the complete_install.js script will proceed silently by default, using the existing configuration values. That is normally the desired behavior for an upgrade installation. However, it is possible to make the script prompt for the above values and update config.js first, like this:

node complete_install.js --configure

When the process completes, a message like this will display on screen:

If this message does not appear, then the installation is NOT complete. 

 Troubleshooting the Installation

If there are any problems installing Profound.js, error messages will show on screen. You may need to scroll up to see them. A log is written for all installations, and errors may include messages like this:

To troubleshoot, review all messages on screen and in the installation log file. If the cause of the problem is not clear, contact Profound Logic Support at support@profoundlogic.com and provide ALL the messages from the screen along with a copy of the installation log file. 

After resolving any problems, run node complete_install.js again to complete the installation.