Taxonomy Icon

Node.js

This lab walks you through the steps required to create, build, and run a cloud native Express.js microservice in less than five minutes.

The microservice can be built by using either:

  • A web browser using the IBM Cloud App Service: This guided approach enables you to build cloud-native apps in minutes. It eliminates the need to manually edit configuration files and allows you to easily add IBM Cloud Services to your project that automatically get provisioned and initialized in your project. Moreover, you can easily attach a DevOps Toolchain to your project using the IBM Cloud Continuous Delivery Service that supports continuous integration and deployment to either a Cloud Foundry or IBM Cloud Kubernetes Service, a managed Kubernetes-based environment on the IBM Cloud.

  • The command line using the NodeServer yeoman generator: This approach provides a local command line utility to create a Node.js cloud native application. This creates applications that are “cloud ready”, including all the necessary configuration to create a DevOps pipeline in your project using Jenkins or the IBM Cloud Continuous Delivery Service, and for deployment to Cloud Foundry, Docker, and Kubernetes technologies, such as those provided by IBM Cloud.

This lab allows you to use either approach. Note that using the IBM Cloud App Service requires you to have an account with IBM Cloud. You may use your existing account or create a new account.

For this lab, we focus on a cloud native web application architecture. We will build a foundational layer microservice that provides a REST API that can be used in a larger Order Management Use Case (architecture diagram below). For more information on a reference implementation for building a cloud-native OmniChannel application using a microservices architecture, refer to the IBM Garage Method.

Learning objectives

At the conclusion of this lab, you will have completed the following steps:

  1. Created an Express.js microservice application

  2. Run the Express.js microservice, with full support for monitoring, request tracking, and liveness checking, and accessed it via the web browser.

Prerequisites

Before starting this lab, you need to clone the project for this lab:

  1. Open your terminal. Click on the Launchpad (rocket logo) in the toolbar, search for “Terminal,” and click on the icon.

  2. cd to a workspace directory and clone the GitHub project containing the NodeMicroservices application we are going to extend:

     git clone http://github.com/seabaylea/NodeMicroservices
    
    • A copy of these instructions is included in the project. You can open the instructions using: open NodeMicroservices/NodeMicroservices.pdf

If you want to use the IBM Cloud App Service, go to Step 1.

If you want to use the NodeServer CLI, proceed to Step 3.

Estimated time

Completing this tutorial should take about 15-20 minutes.

Steps

Step 1. IBM Cloud App Service: Create a Node.js microservice on IBM Cloud

In this section, you will use the IBM Cloud to create an Express.js microservice application using the IBM Cloud App Service web UI. You will:

  • Access the IBM Cloud App Service

  • Create an app from a Starter Kit

    Note: The IBM Cloud App Service jumpstarts cloud native development by allowing a developer to create a project, pick an application starter kit, and deploy a production-ready application within minutes to the IBM Cloud.

    The platform’s code generation technology creates a starter application in the developer’s preferred language and framework, which can be tailored to their needs and use case. Any services that are required in support of the use case are provisioned automatically.

    Developers can debug and test on their local workstation or in the cloud, and then use the DevOps Toolchain to collaborate with others to automate the delivery process.

  • Start by logging into IBM Cloud: http://console.bluemix.net

    • While logged into the IBM Cloud, click on the Navigation menu in the header:

    • Then, click on Web Apps to access the IBM Cloud App Service cloud-native development experience on IBM Cloud.

  • Take a few moments to explore the main Overview screen for the IBM Cloud App Service. From here, you may access and discover hand-picked content related to cloud-native development including the Resources, Community, and Starter Kits sections. As explained, IBM Cloud offers two approaches to building cloud native apps, a web-based and a CLI-based approach. This lab uses the IBM Cloud App Service, which provides a web console.

  • Navigate to the Starter Kits menu on the left-hand side. You will see a range of starter kits that provide production code starting point for a variety of common cloud-native development use cases. They include patterns and technology framework stacks for key programming languages that are commonly used by developers. Have a look through the list of starter kits for other types of projects you may have in the future.

  • Scroll down the list and click on the tile labelled Create Project to create a custom project.

  • Within the Create New Project view, enter a project name of “NodeMicroservice,” and select Node.js as the language.

  • Click Create Project to create the app. The App Details view is now displayed. This view is used to manage various aspects of an app:

    • The main body has an area where you can create new and associate existing services to the app.

    • A panel on the right of the screen offers an area where you may configure a DevOps toolchain.

    • A panel on the bottom right of the screen also offers an area where you may access credentials to any services that you have added to this app.

    • At the top of the screen, it’s possible to download the code to the app without any DevOps configuration.

    • Using the menu in the top right, you can also rename the project or delete it.

      Optionally, you can click Deploy to Cloud to create a toolchain that will give you access to a Git repo for continuous delivery and a Delivery Pipeline to build and deploy to IBM Cloud. To proceed with this path, go to section 5 (Create a toolchain to enable continuous delivery). Otherwise, complete this section and go to section 7 (Run the Node.js Microservice) to run your app locally.

  • Click Download Code to download the project to your local machine to build and run on the command line.

  • Open a terminal window to access the command line. Click on the Launchpad (rocket logo) in the toolbar, search for “Terminal,” and click on the icon.

    Go to the project directory:

     cd ~/Downloads
     unzip -d NodeMicroservice node-microservice.zip
     cd NodeMicroservice
    

    To continue the lab, move on to Section 4 (Run the Node.js Microservice).

Step 2. (Optional) Create a toolchain to enable continuous delivery

In this section, you will create a toolchain that will enable continuous delivery to automate builds, tests, and deployments through the Delivery Pipeline, Gitlab, and more. If you want to skip this step and run your app locally, make sure you completed the previous section and proceed to section 7 (Run the Node.js Microservice).

  1. Click the button &Deploy to Cloud.&

  2. Choose a deployment method. To deploy to Kubernetes, you will first need to create a cluster, which takes about 30 min. If you do not already have a cluster provisioned, it’s recommended to select &Cloud Foundry App& in this lab.

    Note that region, organization, and space are pre-selected with defaults that are OK for this lab.

  3. Click Create.

  4. To view your newly created toolchain, click View Toolchain. You will have access to a new Git repository that has been created for you to manage issues and view and edit your code. In this repo, when you save a commit, a build is automatically kicked off and your updated project is re-deployed.

    Explore your toolchain by selecting the available cards.

  5. Now, let’s enable OpenTracing. Click the Git card under the section “CODE” to open your Git repo.

  6. Navigate to the server/server.js file in your project and enable &appmetrics-zipkin&.

    • Click Edit at the top of the file.

    • Uncomment the code at the top of the file to enable Zipkin request tracking and, optionally, change the serviceName.

    • The top of your file should be:

      var appzip = require('appmetrics-zipkin')({
      host: 'localhost',
      port: 9411,
      serviceName:'NodeMicroservice'
      });
      
    • Once you’ve made the changes, click Commit changes. This has enabled OpenTracing for any request received by the Node.js microservice, and for any outbound requests it makes to other services.

  7. When you commit a change like in step 6, your project will be re-built and re-deployed. Return to your toolchain to open your Delivery Pipeline.

  8. You will see a build stage and a deploy stage. If a stage fails, you will see red. If it terminates successfully, you will see green.

  9. Your app is now deployed to Cloud Foundry in IBM Cloud. To view the health of your deployed app, click on the link in the deploy stage under &LAST EXECUTION RESULT& and append /health to the URL. This is the liveness endpoint. For the sample in this doc, the liveness endpoint is:

http://create-project-lxwbp.mybluemix.net/health

The liveness endpoint provides a response that states whether the application is successfully running. This can be used by Cloud Foundry and Kubernetes to automatically restart the application if it fails or becomes unresponsive.

Step 3. NodeServer CLI: Create a Node.js microservice

In this section, you will use the NodeServer CLI to create an Express.js microservice application that is &cloud ready& and can be run locally or used on any cloud that supports CloudFoundry, Docker, or Kubernetes, including IBM Cloud.

First, let’s install the NodeServer CLI, so we can use it to create a Node.js microservice.

  1. Open a Terminal window to access the command line: Click on the Launchpad (rocket logo) in the toolbar, search for “Terminal,” and click on the icon.

  2. Install the Yeoman utility by running the following command line:

     npm install -g yo
    
  3. Install the NodeServer utility by running the following command line:

     npm install -g generator-nodeserver
    

    This has now installed the NodeServer CLI utility which allows you to quickly create a cloud-enabled Node.js application.

  4. Create a directory with the name of your project.

     mkdir NodeMicroservice
     cd NodeMicroservice
    
  5. Create your Node.js microservice app. Run the following command on the command line:

     yo nodeserver
    

    This will prompt you to answer a number of questions. Provide the following answers:

     [2018-03-14T16:33:08.932] [INFO] generator-nodeserver - Package info ::
     generator-nodeserver 1.0.11
     ? Project name NodeMicroservice
     ? OpenAPI Document (None)  /Users/user/NodeMicroservices/petstore.yaml
     ? Add IBM Cloud Service Enablement? No
    

    This creates a fully working skeleton Node.js project that provides monitoring, metrics, and request tracking, which can then be extended with your application logic.

    As we provided an OpenAPI Document (aka a Swagger definition), additional template code has been added to implement those API calls. The definition we provided is the &Petstore& sample, which provides the REST APIs for a simple petstore.

If you explore the generated assets, you will see that there are a number of configuration files generated for you, including:

  • Jenkinsfile: A pipeline for Jenkins and IBM Cloud Private
  • .bluemix/: A pipeline for IBM Cloud Continuous Delivery Service
  • Dockerfile: A dockerfile to build a Docker image for the application
  • chart/*: A helm chart to enable deployment to Kubernetes
  • manifest.yml: A configuration file for use with Cloud Foundry

Step 4. Run the Node.js Microservice

In this section, you will enable the optional request tracking capability and run the Express.js microservice locally, including viewing its monitoring and metrics capabilities.

  1. Open the server/server.js file in your project and enable &appmetrics-zipkin.&

    1. Open the file: open -a TextEdit ./server/server.js

    2. Uncomment the code at the top of the file to enable Zipkin request tracking. And optionally change the serviceName. The top of your file should be:

      var appzip = require('appmetrics-zipkin')({
       host: 'localhost',
       port: 9411,
       serviceName:'NodeMicroservice'
      });
      

      Once you’ve made the changes, save the file. This has enabled OpenTracing for any request received by the Node.js microservice, and for any outbound requests it makes to other services.

  2. Launch and run the Zipkin server request tracking monitoring service:

     docker run -d -p 9411:9411 openzipkin/zipkin
    

    This will start running the Zipkin monitoring service in a Docker container on port 9411. Zipkin is an open source monitoring solution that is integrated into Docker and Kubernetes deployments, and monitors requests across individual microservices.

     docker run -d -p 9090:9090 -v
     /Users/user/nodemicroservices/prometheus.yml:/etc/prometheus/prometheus.yml
     prom/prometheus
    

    This will start running the monitoring service in a Docker container on port 9090. Prometheus is an open source monitoring solution that is designed to be integrated into Docker and Kubernetes deployments to monitor applications.

  3. Install the dependencies, and run the application:

     npm install
     npm start
    
  4. View the liveness endpoint:

    To check that the application is running successfully, view the liveness endpoint: Liveness endpoint: http://localhost:3000/health

    The liveness endpoint provides a response that states whether the application is successfully running. This can be used by Cloud Foundry and Kubernetes to automatically restart the application if it fails or becomes unresponsive.

    It should report the following:

Step 5. View the Node.js monitoring dashboard

As part of building the Node.js microservice with either the IBM Cloud App Console or the Nodeserver CLI, an in-built monitoring dashboard has been added to the skeleton project.

This provides resource usage metrics for CPU and memory, as well as performance metrics for a large number of capabilities, including inbound and outbound HTTP and WebSocket requests, and outbound requests made of databases and messaging systems.

The dashboard also gives you the ability to request additional data, in the form of function level performance profiling, heap memory usage dumps, and a “node report” that provides a summary of the state of the running application.

  1. View the Monitoring Dashboard

    The monitoring dashboard is hosted by the Node.js microservice on /appmetrics-dash and reachable on the following URL Monitoring Dashboard: http://localhost:3000/appmetrics

    Once you open the dashboard, it will begin to populate with data.

  2. Make some HTTP requests of the Node.js microservice

    Open the liveness endpoint in a new browser window: Liveness endpoint: http://localhost:3000/health

    And drive some load by reloading the page using the b +R key shortcut.

    These requests will appear in the HTTP Incoming Requests and HTTP Throughput views:

  3. Enable and view performance profiling

    The monitoring dashboard provides the ability for you to dynamically enable performance profiling, and to view the data using flame graphs.

    1. Enable performance profiling

      Use the pulldown menu in the top left-hand corner to select Enable Profiling. This enables the profiling, and enables the Profiling tab on the dashboard to allow you to view the collected data.

    2. View the profiling data

      Click on the Profiling tab to see a Flame Graph of the functions using CPU time in the application. The higher the “flame,” the deeper the call stack of the functions. You can select a flame to see its corresponding stack trace in the right window. The wider the cell in the flame, the more time is spent in that function.

The monitoring dashboard also allows you to request heap dumps and node reports, which are written to the local filesystem.

Step 6. View the cloud metrics in Prometheus

As well as building in the monitoring dashboard, which provides monitoring of the specific instance of the Node.js microservice, hosted by the microservice itself, support for Prometheus monitoring is built in.

Prometheus is an open source, cloud-based monitoring solution that collects metrics from running applications and stores them for use in visualization and alerting. The data can be visualized using open source dashboarding technologies such as Graphana, but it also provides its own (simplistic) built-in option.

  1. View the Prometheus Dashboard

    The Prometheus dashboard is reachable on the following URL Prometheus Dashboard: http://localhost:9090/

    This will display the following:

  2. See the status of running services

    Prometheus will report the status of all of the services that it is monitoring, reporting whether they are currently UP or DOWN.

    1. Select the Status pull down menu and choose Targets.

      This reports a very limited set because we are only collecting metrics for the Node.js microservice, and the Prometheus service itself.

      You can also select the &Endpoint& link to see the latest raw data reported from that service.

  3. View the Node.js microservices metrics

    Prometheus provides the ability to run queries and build graphs using the collected data. We can use to this to look at information such as the CPU usage over time, or the responsiveness of HTTP URLs.

    1. Select the Prometheus tab

    2. From the “insert metric” pull down, select process_cpu_used_ratio:

      The “process_cpu_used_ratio” represents the percentage of the machines CPU that is being used by each of the processes.

    3. Click Execute to see the data. This will display in table form:

    4. Click on the Graph tab to see this as a graph over time:

Prometheus has a significantly larger set of capabilities, including setting up alerts. Below is an example of the monitoring that can be built using Prometheus combined with a Graphana custom dashboard:

Step 7. View the cloud request tracking in Zipkin

OpenTracing is a standard for how to add request tracking to microservices. Zipkin is a commonly found implementation of that standard and has been implemented for multiple languages and frameworks.

While the real value of OpenTracing and Zipkin is seen when using multiple microservices, it is important to introduce it into microservices from the beginning, where possible. For Node.js, it can be added with one line of code, but for other languages and frameworks it needs to be developed into the application.

Zipkin is automatically collecting request tracking “spans” from the Node.js microservice, and the data can be viewed at any time. To view the Zipkin request tracking data complete the following steps:

  1. Visit the following URL for Zipkin Monitoring: http://localhost:9411

  2. Select Find Traces to view all of the available Request Tracking spans that Zipkin is aware of.

    You should see a number of traces similar to the following:

    This shows the duration of each request. If there were other microservices involved, you would see the time spent in each microservice that contributed to the overall elapsed time.

Summary

Congratulations! You have completed the lab.

You have successfully built and run a Express.js Microservice that is cloud-ready and can be deployed to any cloud supporting Cloud Foundry, Docker, or Kubernetes, including IBM Cloud and IBM Cloud Private!