Create a Node-RED starter application

In this tutorial, you will learn how to create a Node-RED starter application in the IBM Cloud, including a Cloudant database to store the application flow configuration.

Learning objectives

In this tutorial, you will learn how to:

  • Create a Node-RED Starter application running in the IBM Cloud
  • Secure the application
  • Customize the Node-RED Starter Kit by adding additional nodes

Prerequisites

To complete this tutorial, you need an IBM Cloud account (IBM Cloud Lite, trial, or paid account).

Estimated time

You can complete this tutorial in less than 20 minutes.

Steps

  1. Find the Node-RED Starter in the IBM Cloud catalog
  2. Configure your application
  3. Enable the Continuous Delivery feature
  4. Open the Node-RED application
  5. Configure your Node-RED application
  6. Add extra nodes to your Node-RED palette

Step 1. Find the Node-RED Starter in the IBM Cloud catalog

Follow these steps to create a Node-RED Starter application in the IBM Cloud.

  1. Log in to IBM Cloud.

  2. Open the catalog (1) and search for node-red (2).

  3. Click on the Software tab (3).

  4. Click on the Node-RED App tile (4).

    Catalog entry Node-RED Starter Kit

    This will show you an overview of the Starter Kit and what it provides.

  5. Click on the Create app button (1) to continue.

    Catalog entry Node-RED Starter Kit

Step 2. Configure your application

Now you need to configure the Node-RED Starter application.

  1. On the App details page, a randomly generated name will be suggested – Node RED SSLPD in the screenshot below. Either accept that default name or provide a unique name for your application (1). This will become part of the application URL. Note: If the name is not unique, you will see an error message and you must enter a different name before you can continue.

  2. The Node-RED Starter application requires an instance of the Cloudant database service to store your application flow configuration. Select the region (2) the service should be created in and what pricing plan it should use. Note: You can only have one Cloudant instance using the Lite plan. If you have already got an instance, you will be able to select it from the Pricing plan select box (3). You can have more than one Node-RED Starter application using the same Cloudant service instance.

  3. Click the Create button (4) to continue. This will create your application, but it is not yet deployed to IBM Cloud.

    Create App details page

Step 3. Enable the Continuous Delivery feature

At this point, you have created the application and the resources it requires, but you have not deployed it anywhere to run. This step shows how to setup the Continuous Delivery feature that will deploy your application into the Cloud Foundry space of IBM Cloud.

  1. On the next screen, click the Deploy your app button (1) to enable the Continuous Delivery feature for your application.

    Enable continuous delivery in Node-RED app

  2. You will need to create an IBM Cloud API key to allow the deployment process to access your resources. Click the New button (1) to create the key. A message dialog will appear. Read what it says and then confirm and close the dialog.

  3. Increase the Memory allocation per instance slider (2) to 256MB. If you do not increase the memory allocation, your Node-RED application might not have sufficient memory to run successfully.

  4. The Node-RED Starter kit only supports deployment to the Cloud Foundry space of IBM Cloud. Select the region (3) to deploy your application to. This should match the region you created your Cloudant instance in. Lite users might only be able to deploy to your default region.

  5. Select the region (4) to create the DevOps toolchain.

  6. Click Create (5). This will take you back to the application details page.

    Create the Node-RED Starter app

  7. After a few moments, the Continuous Delivery section will refresh with the details of your newly created Toolchain. The Status field of the Delivery Pipeline will show In progress. That means your application is still being built and deployed.

    Continuous delivery status

  8. Click on the In progress link to see the full status of the Delivery Pipeline.

    Delivery pipeline, view logs

  9. The Deploy stage will take a few minutes to complete. You can click on the View logs and history link to check its progress. Eventually the Deploy stage will go green to show it has passed. This means your Node-RED Starter application is now running.

Step 4. Open the Node-RED application

Now that you’ve deployed your Node-RED application, let’s open it up!

  1. Open your IBM Cloud Resource list by selecting the sidebar menu (1) and then selecting Resource List (2).

    Sidebar menu, selecting resource list

  2. You will see your newly created Node-RED Application listed under the Apps section (1). You will also see a corresponding entry under the Cloud Foundry apps section (2). Click on this Cloud Foundry app entry to go to your deployed application’s details page.

    Cloud Foundry app

  3. From the details page, click the Visit App URL link to access your Node-RED Starter application.

    Visit app URL link on details page

Step 5. Configure your Node-RED application

The first time you open your Node-RED app, you’ll need to configure it and set up security.

  1. A new browser tab will open with the Node-RED start page.

    Configure Node-RED app

  2. On the initial screen, click Next to continue.

  3. Secure your Node-RED editor by providing a username and password. If you need to change these at any point, you can either edit the values in the Cloudant database, or override them using environment variables. The documentation on nodered.org describes how to do this. Click Next to continue.

  4. The final screen summarizes the options you’ve made and highlights the environment variables you can use to change the options in the future. Click Finish to proceed.

  5. Node-RED will save your changes and then load the main application. From here you can click the Go to your Node-RED flow editor button to open the editor.

    Button to launch the Node-RED flow editor

    The Node-RED editor opens showing the default flow.

    Default flow in the Node-RED flow editor

Step 6. Add extra nodes to your Node-RED palette

Node-RED provides the palette manager feature that allows you to install additional nodes directly from the browser-based editor. This is convenient for trying nodes out, but it can cause issues due to the limited memory of the default Node-RED starter application.

The recommended approach is to edit your application’s package.json file to include the additional node modules and then redeploy the application.

This step shows how to do that in order to add the node-red-dashboard module.

  1. On your application’s details page, click the url in the Continuous Delivery box. This will take you to a git repository where you can edit the application source code from your browser.

    Application details page, URL in the continuous delivery box

  2. Scroll down the list of files and click on package.json. This file lists the module dependencies of your application.

    In list of files, find the package.json file

  3. Click the Edit button

    Edit button for package.json file

  4. Add the following entry to the top of the dependencies section (1):

     "node-red-dashboard": "2.x",
    

    Note: Do not forget the comma (,) at the end of the line to separate it from the next entry.

    Add a Commit message (2) and click Commit changes (3)

    Editing package.json file

  5. At this point, the Continuous Delivery pipeline will automatically run to build and deploy that change into your application. If you view the Delivery Pipeline you can watch its progress. The Build section shows you the last commit made (1) and the Deploy section shows the progress of redeploying the application (2).

    Status of Node-RED Starter app in continuous delivery pipeline

  6. Once the Deploy stage completes, your application will have restarted and now have the node-red-dashboard nodes preinstalled.

Summary

Congratulations! You have now created a Node-RED application that is hosted in the IBM Cloud. You have also learned how to edit the application source code and automatically deploy changes.

Nick O'Leary