Contents


Running Node-RED on IBM i: Installation and first flow

Install Node-RED on your IBM i system and create Node.js programs with a browser-based flow editor

Comments

In a digital world, companies need to be agile to react faster to their customer expectations. Software solution designers and developers live with these same imperatives and need to deliver applications quickly. But how can they make sure they implement the right solutions and avoid wasting time and money on implementing inappropriate solutions?

The prototype (and fast prototyping) is an early model or experiment to rapidly try solutions. Many prototypes fail. But because they fail, and sometimes fail fast, prototypes can be lifesavers, preventing the waste of resources. As a result, unforeseen difficulties are identified earlier, and the costs associated with wrong design or late design changes are avoided.

This rapid iterative cycle of reflection and construction is what allows product designers and developers to learn quickly through experience and customer feedback.

Companies using IBM i have the same imperatives. They can use rapid prototyping to be able to address their customer expectations.

Initially developed for wiring the Internet of Things (IoT), Node-RED is one of new web-based tools and platforms that have emerged for rapid development and prototyping.

In this article, we will see what is Node-RED and how we can install it on IBM i to provide a fast-prototyping solution.

What is Node-RED

Node-RED (https://nodered.org/) is a flow-based programming tool, originally developed by the IBM Emerging Technology Services team (in early 2013) and now a part of JS Foundation.

Traditional development can be very technical, but Node-RED enables you to concentrate on the logic of your workflow and allows fast prototyping.

Node-RED consists of a Node.js-based runtime with a flow editor accessed through a web browser. Within the browser, you create your application by dragging nodes from a customizable palette into a workspace and start to wire them together. With a single click, the application is deployed back to its runtime.

Figure 1. Node-RED web interface

Nodes can be IoT devices, web APIs, cloud services or any building block that can receive and send messages. Nodes encapsulate complex building blocks such as databases, APIs, protocol handlers, logic, and so on.

The palette of nodes can be easily extended by installing new nodes created by the community and the flows you create can be easily shared as JSON files.

While most programming in Node-RED is done visually using predefined functions (nodes), additional functionalities can be added in JavaScript.

Node-RED is a full Node.js application, and Node.js is supported by the IBM i platform. Therefore, Node-RED can be deployed on IBM i. The IBM i Open Source Solutions licensed program offering (LPO) 5733OPS was created to support open source technologies on IBM i. It is included within the bonus pack for the IBM i operating system. After being installed, this no-charge LPO is serviced through PTF group SF99225.

What you'll need

To install Node-RED on your IBM i system, you'll need:

  • 5733OPS, option 10 - Node.js v6.x
    • 5733OPS supports only IBM i 7.1 and later
  • 5733OPS, option 3 – Chroot with gcc
  • 5733OPS, option 7 – Tools (optional)
  • 5770SS1, option 33 – Portable App Solutions Environment
  • 5733SC1, option 1 – OpenSSH, OpenSSL, zlib
  • 5770DG1, *BASE – IBM HTTP Server for i

If you need to install Node.js, you can refer to the Native JavaScript applications on IBM i with Node.js IBM® developerWorks® article from Xu Meng and Zheng Chang Qing (updated May 10, 2017).

Prepare Node-RED installation

Open a shell session on your IBM i system. You can use QSHELL (QSH) or PASE (CALL QP2TERM), or start the Secure Shell (SSH) server (using the STRTCPSVR *SSHD command) and remotely connect to IBM i. I recommend using SSH. Read Jesse Gorzinski's article, Eight Reasons to Embrace SSH at IBMSystemsMag.com to be convinced. Remote SSH solution is used in this article.

Note:

Using QShell requires some preconfigurations. In QShell sessions, some Node.js applications might throw a signal 5 error. This error is caused by a thread limit of QShell. You can remove this limit by adding the QIBM_MULTI_THREADED environment variable with a value Y. Then, restart the Qshell session. This variable determines if the processes started by qsh can create multiple threads. When the value of the variable is Y, all child processes started by qsh can start threads. The default value is N. The following CL command sets the system environment variable, enabling QShell for multithread capability:

ADDENVVAR ENVVAR(QIBM_MULTI_THREADED) VALUE(Y)

If you want this configuration to be permanent and available for all jobs (not only current), set it at the system level:

ADDENVVAR ENVVAR(QIBM_MULTI_THREADED) VALUE(Y) LEVEL(*SYS)

The recommended Node.js version for Node-RED is 6.x, supported by IBM i. But, as IBM i supports several Node.js versions at the same time (installed and running), we need to configure our environment to use Node.js v6.

  1. Run the following command to use Node.js version 6:
    $ /QOpenSys/QIBM/ProdData/OPS/Node6/bin/nodever.sh 6
  2. You can verify the Node.js runtime version level and npm version using the following commands (npm is the default package manager for Node.js. It allows to install, share, distribute code, and manage dependencies in your projects. See npmjs.com for further information). With PTF group SF99225 Level 5, you can obtain versions as shown below:
            $ node –v
            v6.9.1
            $ npm –v
            3.10.8

As Node-RED is a Node.js application (based on Node.js modules), it can be installed globally in the system directory or locally in a specific directory. In this article, we will perform a global installation.

npm global versus npm local installation

In npm, you can install packages using any one of the following methods:

  • Globally: This method installs modules in {node_path}/lib/node_modules, and copy the executable files in {node_path}/bin, where {node_path} is /QOpenSys/QIBM/ProdData/OPS/Node6/ (using Node.js v6).

    You can identify the location where the packages will be installed using the npm root –g command:
            $ npm root -g
            /QOpenSys/QIBM/ProdData/OPS/Node6/lib/node_modules
  • Locally: This method installs your package in the current working directory. Node modules will be available in ./node_modules, and the executable files will be available in ./node_modules/.bin/.

You can read more about npm and types of installation at: https://docs.npmjs.com/getting-started/what-is-npm

If you decide to install Node-RED locally, it will be installed in your current directory. The npm root command enables you to know where Node-RED will be installed. Installing it as a non-global module doesn't add the node-red command to your system path. Only node-red-pi command is added to <YOUR_DIRECTORY_PATH>/node_modules/node-red/bin/.

So, to start it, you need to use a Bash script provided by Node-RED: <YOUR_DIRECTORY_PATH>/node_modules/node-red/bin/node-red-pi.

Install GCC for Node-RED dependencies compilation

During Node-RED installation, optional dependencies require a compiler in order to build them. If GCC is not installed, errors may be reported by the node-gyp command (which is a Node.js native add-on build tool used by npm to install Node-RED). These are typically non-fatal errors that cannot stop the installation of Node-RED. Node-RED can work without these optional dependencies, but later, you may find additional node modules that require the ability to compile native code.

That's why we will install GCC.

GCC is a popular C language compiler used for compiling open source projects. To get it, use scripts provided by 5733OPS, option 3 - chroot with gcc. These scripts allow to download packages from the perzl.org AIX open source website. Refer to the IBM Open Source Technologies / Option 3, chroot scripts page for more information.

Missing C/C++ libraries?

When you install GCC for the first time, you have to run a script that enable you to install RPM Package Manager (RPM) packages from perzl.org (see IBM Open Source Technologies / Option 3, chroot scripts page).

Using GCC as-is with libraries provided, you could compile majority of Node.js modules. But sometimes, for specific Node.js modules, you will have to provide and add specific C/C++ libraries to the GCC environment.

To do that, you can use standard wget (supported by 5733OPS, OPT 7 – Tools) and rpm commands to install your new library from http://www.oss4aix.org/download/RPMS/.

You can also add the required library to the file containing the list of libraries to be installed during GCC installation and run or re-run installation scripts. That's the way we will use hereunder to install a new library required by optional bcrypt module installed by Node-RED.

During installation, Node-RED installs an optional Node.js package, bcrypt. This package is optional but required for Node-RED user authentication (configured later in this article). bcrypt needs to be compiled, but due to missing C/C++ package, compilation cannot succeed.

Figure 2. bcrypt compilation fails

If you want to install bcrypt, you must add the missing C/C++ package to the list of packages to be installed during GCC installation. The file containing the list is /QOpenSys/QIBM/ProdData/OPS/GCC/pkg_perzl_gcc-4.8.3.lst.

You can edit this file using the following IBM i command:

EDTF STMF('/QOpenSys/QIBM/ProdData/OPS/GCC/pkg_perzl_gcc-4.8.3.lst').

Or, from a Shell session:

        $ TERM=xterm
        $ export TERM
        $ vi /QOpenSys/QIBM/ProdData/OPS/GCC/pkg_perzl_gcc-4.8.3.lst
Note:

Setting the TERM variable defines terminal type, allowing vi to be used.

Then, add the following line to the end of file, and save and exit editor.

          …
          http://www.oss4aix.org/download/everything/RPMS/libstdc++-devel-4.8.3-1.aix6.1.ppc.rpm

The GCC environment file is now configured to support Node-RED full installation.

We can now install GCC.

We will do a simple GCC installation (refer to the chroot scripts page to see all types of installation available, such as installation in chroot location, and options). To install GCC, run following commands:

              $ cd /QOpenSys/QIBM/ProdData/OPS/GCC
              $ ./pkg_setup.sh pkg_perzl_gcc-4.8.3.lst

After installing GCC, we can install Node-RED.

Install Node-RED

The easiest way to install Node-RED is to use the Node.js package manager, npm.

As mentioned before, in this case, we perform a global Node-RED installation.

Installing it as a global module adds the node-red command to your /QOpenSys/QIBM/ProdData/OPS/Node6/bin system directory.

To start Node-RED installation, run the following command:

$ npm install -g --unsafe-perm node-red
Note:

Setting the unsafe-perm flag allows to run scripts with root privileges. The reason for using the --unsafe-perm option is that when the node-gyp command tries to recompile any native libraries, it tries to do so as a nobody user and often fails to get access to certain directories. Allowing node-gyp to run as root using this flag avoids this.

Extract from npm documentation:

unsafe-perm

  • Default: false if running as root, true otherwise
  • Type: Boolean

Set to true to suppress the UID/GID switching when running package scripts. If set explicitly to false, then installing as a non-root user will fail.

Node-RED and dependencies packages will be downloaded and installed into the system path, /QOpenSys/QIBM/ProdData/OPS/Node6/lib/node_modules.

Figure 3. Node-RED installation

You can check installation (and the version installed) using the following npm command:

        $ npm list -g node-red 
        /QOpenSys/QIBM/ProdData/OPS/Node6/lib
        `-- node-red@0.17.5

If you look at the Node.js v6 directory, you can see that Node-RED commands were added:

        $ ls /QOpenSys/QIBM/ProdData/OPS/Node6/bin
        node node-red node-red-pi nodever.sh npm

By default, the Node-RED command access permissions allow everybody to launch Node-RED ('777'). If needed, you can change it using the chmod command.

Figure 4. Node-RED command permissions

We are now ready to run Node-RED.

Note:

Currently, the version of Node-RED is 0.17.5. When a new version is available, we can update using same npm command used for installation but with the update command:

$ npm update -g --unsafe-perm node-red

Node-RED basic configuration (authentication and port number)

Node-RED can be configured to take in account your environment requirements, in terms of network, security, and so on.

Its configuration is based on the properties defined in the settings.js file.

Location of this file is determined in the following order:

  • In the value specified by the --settings|-s command-line argument
  • In the user directory if it was specified by the --userDir|-u command-line argument
  • In the default user directory: $HOME/.node-red/settings.js
  • In the Node-RED install directory: /QOpenSys/QIBM/ProdData/OPS/Node6/lib/node_modules/node-red/settings.js

Node-RED also provides a default settings.js file that will be used in the absence of a user-provided settings file. It can also be used as a starting point for creating your own settings file. It can be seen on GitHub here.

All configuration properties are explained in Node-RED User Guide / Configuration.

Let's see how to configure the Node-RED UI port number and user authentication.

By default, access to the Node-RED editor web interface is not authenticated and everyone can connect. We restrict access to authenticated users by performing the following steps:

  1. Generate the settings.js file.
    To generate a default settings.js file, we just have to start Node-RED without any parameter specified. This will automatically create a default file in the $HOME/.node-red directory.
    To start Node-RED, enter the following command: /QOpenSys/QIBM/ProdData/OPS/Node6/bin/node-red
    Figure 5. Start Node-RED

    In this example (shown in Figure 5), you can see that a settings.js file has been created in the
    /home/CLALEVEE/.node-red directory. We will use it next to store our configuration.
    Press Ctrl+C to end Node-RED. We will restart it after completing the configuration.

    Note:

    QSH does not support using the interrupt key (typically <Ctrl+C>) to send the SIGINT signal to the foreground process group. As an alternative, you can use <SysReq> + <2> from an interactive shell session to send the SIGINT signal to the shell interpreter process and any currently running child processes.

  2. Generate a user-encrypted password for authenticated user.
    Node-RED supports two types of authentication:
    • Username/Password credential-based authentication
    • Authentication against any OAuth/OpenID provider such as Twitter or GitHub (since Node-RED 0.17)
    Username /password are not related to *USRPRF objects. It is just a list of users (in JSON format) declared in the settings.js file. We will use this solution in this article.

    As password is stored in hashed format, we first need to generate a suitable password hash. We will use the bcryptjs module from Node-RED installation. Use the following Node.js line of code to generate a hashed password (replace 'Passw0rd' with the password to be hashed).

    $ node -e "console.log(require('/QOpenSys/QIBM/ProdData/OPS/Node6/lib/node_modules/
    node-red/node_modules/bcryptjs').hashSync(process.argv[1],8));" Passw0rd
    Note:

    The second argument of the hashSync function ("8" is this example) is the "salt" to be used in encryption. The "Salt" is random data that is used as an additional input to a one-way function that hashes a password or passphrase.

    The tool hashes the given password and then prints out the hash that can be copied into the settings file.

    Figure 6. Hashing password
  3. Update settings.js file for authentication.
    Now we can update the settings.js file to set up authentication, declare a user, and change the default Node-RED UI port number.
    You can edit this file using the following IBM i command:
    EDTF STMF('<your_home_directory>/.node-red/settings.js')

    Or, from an SSH session:

            $ TERM=xterm
            $ export TERM
            $ vi <your_home_directory>/.node-red/settings.js
    Note:

    Setting the TERM variable defines the terminal type, allowing vi to be used.

    Search for the //adminAuth keyword to find the "Securing Node-RED" paragraph.

    Figure 7. Node-red AdminAuth configuration

    You can now remove the comment delimiters ('//') and add your new user.
    You must obtain something as shown below:

            // Securing Node-RED
            // -----------------
            // To password protect the Node-RED editor and admin API, the following
            // property can be used. See http://nodered.org/docs/security.html for details.
            adminAuth: {
               type: "credentials",
               users: [{
                   username: "admin",
                   password: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                   permissions: "*"
                },
                {
                   username: "<YOUR_USERNAME>",
                   password: "<HASHED_PASSWORD_GENERATED>",
                   permissions: "*
                }]
               },

    By default, an admin user profile is pre-configured in the Node-RED settings.js file. The password is password. Of course, it is highly recommended to remove this admin user (and create a new one) or to change the default password using the bcrypt Node.js module, as we have done before.

  4. Update port number in the settings.js file.
    We are now going to change the TCP port number. In the settings.js file, search for the uiPort keyword.
    Figure 8. Change Node-RED TCP port number

    The code you found (mentioned above), specifies to use a parameter from environment (if exist) or 1880, the Node-RED default port number. Assuming that we don't want to use 1880, replace 1880 by 1988.

            module.exports = {
               // the tcp port that the Node-RED web server is listening on
               uiPort: process.env.PORT || 1988,
  5. Save and quit the editor.

Node-RED basic configuration is done. We can now start Node-RED.

Start Node-RED

To start Node-RED, use the node-red command in /QOpenSys/QIBM/ProdData/OPS/Node6/bin.

This command accepts parameters to define the running environment.

Use the node-red –h command to list the allowed parameters.

Figure 9. node-red command

But, as we defined a new configuration in the settings.js file, we don't need to define parameters when launching Node-RED.

Notice that if there is an error in the settings.js file, starting Node-RED will identify the problem immediately.

In the example shown in Figure 10, Node-RED cannot start due to the error in line 31 of the settings.js file (missing comma in line 30).

Figure 10. Starting Node_RED with error

To start Node-RED, enter: /QOpenSys/QIBM/ProdData/OPS/Node6/bin/node-red.

Note:

You can have several configuration files and choose the one to use at start-up: /QOpenSys/QIBM/ProdData/OPS/Node6/bin/node-red –s <PATH>/settings_bis.js. This can be useful to switch configurations or start multiple Node-RED instances.

Figure 11. Starting Node-RED

You can see that Node-RED is now listening on port 1988 instead of the default port 1880.

Node-RED log displays http://127.0.0.1:1988. You need to use your IBM i IP address or host name to remotely connect to the Node-RED UI.

Note:

To start Node-RED in a non-interactive mode, create a shell script, start.sh, and set up the Node.js environment (for example, Node.js version, Node-RED user directory, and the settings.js file) before starting Node-RED. Refer to the following start.sh example script:

        #!/usr/bin/sh
        /QOpenSys/QIBM/ProdData/OPS/Node6/bin/nodever.sh 6
        /QOpenSys/QIBM/ProdData/OPS/Node6/bin/node-red -u /home/CLALEVEE -s
        /home/CLALEVEE/.node-red/settings.js

Then, submit a new batch job using the QSH command to run this script:

=>SBMJOB JOB(QSH CMD('/<YOUR_DIR>/start.sh'))

Open your browser and connect to http://<YOUR_SERVER_IP_ADDRESS>:1988.

Figure 12. Node-RED user authentication

Enter user name and password as defined previously in the settings.js file.

You now have access to the Node-RED UI.

Figure 13. Node-RED web UI

Now, let's look at the Node-RED interface and create a flow.

Create your first flow

Node-RED allows you to build applications using a graphic editor, by connecting the nodes you need. To create a new stream, drag the nodes from the palette (left menu) to the workspace (flow tab) and connect them as needed.

Figure 14. Node-RED web UI

If you're not familiar with Node-RED, try creating your first flow by referring to the Node-RED "Creating your first flow" tutorial. Figure 14 shows the result.

Where is the flow stored?

By default, Node-RED stores your data in the user's home directory: $HOME/.node-red.

When you create flows in Node-RED on IBM i, they will be stored in a text file (in JSON format). For example, flows_<HOSTNAME>.json.

Specifying a new user directory when starting Node-RED allows to use another flow file.

        $ /QOpenSys/QIBM/ProdData/OPS/Node6/bin/node-red -u /home/user2
        15 Sep 11:38:47 - [info]
        
        Welcome to Node-RED
        ===================
        
        15 Sep 11:38:47 - [info] Node-RED version: v0.17.5\
        15 Sep 11:38:47 - [info] Node.js version: v6.9.1
        15 Sep 11:38:47 - [info] OS400 3 ppc BE
        15 Sep 11:38:48 - [info] Loading palette nodes
        15 Sep 11:38:49 - [warn] -----------------------------------------------------
        15 Sep 11:38:49 - [warn] [rpi-gpio] Info : Ignoring Raspberry Pi specific node
        15 Sep 11:38:49 - [warn] -----------------------------------------------------
        15 Sep 11:38:49 - [info] Settings file : /home/user2/settings.js
        15 Sep 11:38:49 - [info] User directory : /home/user2
        15 Sep 11:38:49 - [info] Flows file :
        /home/user2/flows_ibmi7.ibm.com.json
        15 Sep 11:38:49 - [info] Creating new flow file
        15 Sep 11:38:49 - [info] Server now running at http://127.0.0.1:1880/
        15 Sep 11:38:49 - [info] Starting flows
        15 Sep 11:38:49 - [info] Started flows

Of course, we can implement more complex flows.
Let's try to create a real-time chat app.

More complex flow, import flow

To create a real-time chat web app, import the code provided by Luiz Gustavo Ferraz Aoqui and Bradley Steinfeld in the IBM developerWorks article, "Build a real-time chat app with Node-RED in 5 minutes".

This article describes how to create a chat application in Node-RED on IBM Bluemix®, but, as it is Node-RED, it can run also on IBM i.

You need to get the (JSON) code, import it into Node-RED on IBM i, and deploy it.

  1. Get the code.
    To get the code, go to IBM developerWorks article, step 2 and click the Project repository" link, and copy the entire nodechat.json file's content.
  2. Import the code.
    Go back to IBM i Node-RED editor in your browser, click the menu icon at the top-right corner (highlighted in Figure 15) and click Import > Clipboard.
    Figure 15. Import flow into Node-RED

    Then, paste the nodechat.json file's content that you copied from the repository, click new flow, and then click Import.

    Figure 16. Import nodes

    Click somewhere on the blank sheet to paste nodes.
    Optional: Refer to article "Build a real-time chat app with Node-RED in 5 minutes", step 4 to understand what each node does.
  3. Update the code.
    We didn't configure Node-RED to use secure network protocols (such as HTTPS, WSS, and so on). So, we have to update the code, changing WSS (WebSockets over SSL/TLS) by WS (WebSockets) in HTML links.
    Figure 17. Edit Template node

    Double-click the template node (see arrow on Figure 17).
    Find the WebSocket URL and replace wss:// by ws://.

    Also, enter payload in the Set property field as shown in Figure 18.

    Figure 18. WebSockets URL

    Click Done to validate the changes.

  4. Deploy the code.
    Click Deploy to deploy and make your application live. A message, Successfully deployed, appears at the top of the window.

We can now test this real-time chat web application by performing the following steps:

  1. Open a new tab on your browser and enter the URL: http://<IBM_i_IP_ADDRESS>:1988/chat, where<IBM_i_IP_ADDRESS> is the host name or the IP address of your IBM i system.
  2. You now have access to your chat application running.
    Enter a user name in the field on the left, write a message on the box on the right, and click Send.
  3. Open the chat in a second window (using the same URL).
    Notice that you can receive the messages instantaneously.
    Figure 19. Real-time web chat application

You can see how simple it is to import or export an application from one Node-RED environment to another, and to create a real-time chat application with only six nodes and one HTML page.

Conclusion

As we have just seen, thanks to the support of Node.js brought by 5733OPS, the installation of Node-RED on IBM i is easy.

Node-RED provides the possibility to create innovative prototypes and applications (such as a real-time chat application with only six nodes and one HTML page ) and to take advantage of Node-RED community contributions (nodes import / export).

So, let's concentrate on business innovation and prototype on Node-RED without bothering about any technical complexity!

In the next article, we'll see how to install cognitive IBM Watson® nodes in Node-RED and implement a IT helpdesk chatbot to automate the processing of passwords related tickets using the IBM Watson Conversation service on IBM Bluemix, and of course, Node-RED on IBM i!

Stay tuned.

References

GCC on IBM i

Node-RED

Node.js

Node-RED flow example


Downloadable resources


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=IBM i
ArticleID=1050747
ArticleTitle=Running Node-RED on IBM i: Installation and first flow
publish-date=10162017