Before you start:

This page describes the command line installation process.
- See Profound Installer for an alternative GUI installation process.
Before starting the installation, please be sure to review the installation prerequisites.
Applications and configurations created for an earlier major release may need adjustments when upgrading to a new major release.
- Make sure to review the migration guides before upgrading from an earlier major release.

Overview

This page describes the command line process for installing or upgrading Profound.js 7. The installation/upgrade process has three main steps:

Select the Node Package Manager (NPM) tag name for Profound.js 7 using the table below.
Start the Installation Process by installing the profoundjs package using NPM.
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 release of Profound.js 7 unless your application has specific requirements.

To upgrade within the Profound.js 7 release series, use the latest-7 tag to get the latest 7.x.x version. Releases within a major release series are always backwards compatible.
To pin an instance to a specific minor release series, use a latest-7.<minor> tag. The available tags can be listed with npm view profoundjs dist-tags;
When upgrading to a new major release series, make sure to check the migration guides.

NPM Tag	Profound.js Major Release	Supported Node.js Versions

NPM Tag	Profound.js Major Release	Supported Node.js Versions
No tag (default installation)	Profound.js 7	24, 22, 20
latest-7	Profound.js 7	24, 22, 20
latest-7.<minor>	Profound.js 7, pinned to one minor release (for example, latest-7.29)	24, 22, 20

Starting the Installation Process

Always use the most recent supported version of Node.js, unless your application has specific requirements.

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}

cd /
mkdir profoundjs
cd profoundjs
npm install profoundjs@<tag_name>

Pinning the Profound.js Version

Installing by tag records Profound.js in package.json as a caret range, for example:

package.json after npm install profoundjs@latest-7

"dependencies": {
  "profoundjs": "^7.33.0"
}

A caret range floats. Any later npm install in this directory – run for any reason, including installing an unrelated package – can resolve ^7.33.0 to a newer 7.x.x release and silently move the Node.js components forward. If complete_install.js is not run afterwards, the IBM i Connector library is left behind and requests from IBM i fail with Version Mismatch (PJS0014).

To install a version that cannot drift, use --save-exact:

npm install --save-exact profoundjs@7.33.0

This records the version without the caret, so repeat installs resolve to exactly that release:

"dependencies": {
  "profoundjs": "7.33.0"
}

Two further habits keep an instance predictable:

Keep package-lock.json - It records the exact resolved versions of Profound.js and every dependency. Deleting it removes the only record of what is actually installed;
Re-run complete_install.js after any npm command - This is what keeps the IBM i half in step (see complete_install.js Command Reference).

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:

npm WARN enoent ENOENT: no such file or directory, open 'C:\Users\Alex\pjs_instance\package.json'
npm WARN pjs_instance No description
npm WARN pjs_instance No repository field.
npm WARN pjs_instance No README data
npm WARN pjs_instance No license field.

These warning messages do not mean that the installation failed. They simply mean you did not have a package.json file to describe 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

complete_install.js must be run after every npm install in this directory – not only during a first-time installation, and not only when Profound.js itself was the package being installed.

npm updates the Node.js components. This script is what installs and updates the IBM i Connector library to match. If the two are left at different versions, requests from IBM i fail with Version Mismatch (PJS0014).

An additional step is required to complete the installation. Run this command from within your installation directory:
_{Command to Complete the Installation}

node complete_install.js

For a new installation – when a config.js file is not present in the installation directory – the complete_install.js script prompts for details on how to set up the Profound.js installation. The default for each prompt is shown in parentheses, so if the default is appropriate you can just press Enter.

The prompts you see depend on your platform and on your answers. On Windows, Linux, and Mac only the port and sample code prompts normally appear; the rest are IBM i only. Answering n to a prompt also skips the prompts that depend on it.

Prompt	Default	Asked on	What it does

Prompt	Default	Asked on	What it does
Specify port number for Profound.js server	`8081`	All platforms	The port number the Profound.js server listens on. Each instance on a system needs its own port.
Install with Git integration?	`y`	Windows, Linux, and Mac – and only on Node.js 16 or earlier	Installs the components needed for Git integration. It is not asked on IBM i, and not asked on Node.js 18 or above – which means it does not appear during a normal Profound.js 7 installation.
Install Profound.js Connector IBM i ILE components?	`y`	IBM i only	Installs the Profound.js Connector, which allows native IBM i applications to interface with Profound.js. Answer `n` to skip it.
Enter Profound.js Connector library name	`PROFOUNDJS`	IBM i only, if the Connector is being installed	The IBM i library the Connector is installed into. Stored as connectorLibrary. Give each instance on a system its own library (see Using Multiple Instances (IBM i)).
Enter Profound.js Connector library IASP	`*SYSBAS`	IBM i only, if the Connector is being installed	An IASP to install the Connector library onto. Keep `SYSBAS` if you are not using an IASP. Stored as connectorIASP (see* IASP Support).
Create/replace server instance configuration for STRTCPSVR/ENDTCPSVR commands?	`y`	IBM i only	Configures the instance to start and end with the STRTCPSVR/ENDTCPSVR commands. Answer `n` and the instance must be started manually from a PASE shell (see Starting and Ending Profound.js Instances).
Server instance name	`PROFOUNDJS`	IBM i only, if STRTCPSVR control was selected	The job name for the server instance running in the `PROFOUNDJS` subsystem. It also names the instance configuration directory, `/profoundjs-base/instances/INSTANCE_NAME`.
Specify CCSID for instance	`37`	IBM i only, if STRTCPSVR control was selected	The CCSID used for the server job and its associated SQL server (`QSQSRVR`) jobs. Use the same EBCDIC CCSID as your existing IBM i applications so character conversion is correct.
Specify Node.js path for instance	The Node.js binary running the installer	IBM i only, if STRTCPSVR control was selected	The Node.js binary used to run the instance. This is how a specific Node.js version is selected – see Choosing a Node.js path below.
Autostart server instance	`y`	IBM i only, if STRTCPSVR control was selected	Whether the instance starts automatically when TCP/IP starts.
Integrate with separate Profound UI instance?	`n`	IBM i only	Configures integration with a separate Profound UI instance. Answer `y` only if you are using Profound UI.
Profound UI instance name	`PROFOUNDUI`	IBM i only, if Profound UI integration was selected	The Profound UI instance to integrate with. This sets staticFilesDirectory and profounduiLibrary to that instance’s document root directory and installation library.
Install sample code?	`y`	All platforms	Installs the sample modules, workspaces, plugins, and other sample code that ship with the product. The same result can be forced on an upgrade with `node complete_install.js --installSamples`.
Provide the username and password that the application should use to connect to the database.	`n`	IBM i only	Answer `y` to have the installer collect and store the IBMi connector credentials. You are then prompted for User, Password, and Relative encrypted file name – the credentials file, stored in the root server directory, which defaults to `credentials`.

Choosing a Node.js Path

The default is the path of the Node.js binary used to run the installation process. Values such as these can be used to select an alternate Node.js version:

/QOpenSys/pkgs/bin/node - The IBM i system default Node.js version;
/QOpenSys/pkgs/lib/nodejs20/bin/node - Node.js 20;
/QOpenSys/pkgs/lib/nodejs22/bin/node - Node.js 22.

This value is stored as the nodePath directive in the instance configuration file, and can be changed later (see Starting and Ending Profound.js Instances).

Transformation Prompts

The last two prompts in the table appear on IBM i only, and are used for Profound.js Transformation installations.

These two options must be answered together. Enabling database credentials without enabling the Transformation installation – or the reverse – causes complete_install.js to stop with an error.

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:

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

Installation Process