The installation/upgrade process has three main steps:

1. Select the desired major release to install and Node Package Manager (NPM) tag name using the table below.

2. Start the Installation Process by installing the profoundjs package using NPM.

3. Complete the Installation Process by running the complete_install.js script.

Selecting an NPM Tag

For new installations, it's recommended to use the most recent major release of Profound.js unless your application has specific requirements.

For upgrade installations:

• To upgrade within your currently installed major release series, use the tag name that corresponds to your current installation. For example, use latest-6 to get the latest 6.x.x version. Releases within a major release series are always backwards compatible.

• When upgrading to a new major release series, make sure to check the migration guides.

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@<tag_name>. This will download all package dependencies and install the product.

Sample commands to start the installation process for Profound.js

 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:

Command to Complete the Installation

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:

• 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, using the existing configuration values. However, you can force the install script to prompt the for new configuration values by adding the switch “--configure” to the command:

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

Open

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 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.