How-tos

Integrate your Nexus-hosted npm registry into your Node.js toolchain

Share this post:

By now, you probably know that with toolchains in IBM® Bluemix® Continuous Delivery, you can build a Node.js app in the Delivery Pipeline and push the app to Bluemix. But did you know that you can integrate a Nexus server with Delivery Pipeline by using a toolchain? You might have a Nexus server to manage node modules that need to be consumed by only your app; they don’t need to be pushed to the global registry. You can use Nexus to both store and provide node modules during your Delivery Pipeline builds.

For example, you might have a GitHub repo with an echo node module and a GitHub repo with an express app that consumes your node module. With Nexus, you can keep the builds of those node modules separate.

The process to set up the Nexus tool integration has two main steps:

  1. Add Nexus to your toolchain.
  2. Add an npm build job to your Delivery Pipeline.

Note: You must run your own Nexus server in order to integrate it with toolchains.

Adding Nexus to your toolchain

From your toolchain’s Overview page, click Add a Tool. On the Nexus configuration page, enter these details:

  • A name for the integration, such as npm-nexus
  • The console URL for your Nexus server
  • The repository type, such as npm registry
  • An email address
  • Your npm registry authentication token; for example,
    echo -n nexus_user_id:nexus_password | base64 -w0 -
  • The URL of your private npm registry
  • The URL of your public npm registry

nexusIntegration

For more information about the Nexus server setup, see Nexus server configuration details.

Adding an npm build job to your pipeline

Add a build job to your pipeline and for the builder type, select NPM Build. For the tool integration type, make sure that Nexus is selected. If you use the default selection for the tool instance name, the npm build job will retrieve its configuration information from the only Nexus integration in your toolchain.

npmBuildJob

Building your npm module

The npm build job preconfigures your .npmrc file with the public registry and authentication information that you provided in your Nexus integration. An npm install or npm run build will use your Nexus server to retrieve required modules.

The npm build job also provides environment variables that can be used when you run your build command:

  • NPM_NAME: The name of the service instance
  • NPM_USER_ID: The email address for the npm registry
  • NPM_TOKEN: The token or password for the npm registry
  • NPM_RELEASE_URL: The private npm registry
  • NPM_MIRROR_URL: The proxy npm registry, which is used as the default npm registry
  • NPM_MODULE_NAME: The module name of the package.json file that is at the root of the workspace, if available

Publishing your npm module

To publish your module to your private registry, create another build job that uses NPM Build as the builder type. You must provide extra information to the publish command line because the .npmrc registry points to your public registry. To publish the module to your private registry, use the NPM_RELEASE_URL environment variable.

npmPublishJob

Support Continuous Delivery in your pipeline by using Nexus

Unlike Maven, an npm registry has no native concept of snapshots. Snapshots are pre-release versions of modules that can be repeatedly pushed to a repository. To work with a pipeline that builds the module and publishes it, each commit would need to increase the module version. But with a little help, NPM Build can support snapshots of a node module that can be used with another module or app without relying on a developer to update the module version on every commit.

Configure your module version in the package.json file to a pre-release version; for example, 1.0.6-SNAPSHOT.0. The -SNAPSHOT.0 suffix represents a pre-release version of 1.0.6. For details about node module versions, see the semantic versioner for npm.

In your publish build job, select the Increment snapshot module version check box.

npmPublishJob

Before you run your npm publish command, the NPM Build job selects the highest node module version from the package.json file and your NPM_MIRROR_URL registry. Then, the NPM Build job increments that version by using the semantics that are defined by npm semver. For example, 1.0.6-SNAPSHOT.5 becomes 1.0.6-SNAPSHOT.6 and is written into the local package.json file. The new version is used during the npm publish, but the NPM Build job does not deliver this change to the SCM repository.

The app that depends on the module sets the dependency version to ^1.0.6-SNAPSHOT.0 to always pick up the latest snapshot of that module.

Nexus server configuration details

Storing your node modules in a private registry during your builds is a common use case. In Nexus, you can support this use case by creating three registries:

  1. A hosted npm registry to store your private modules
  2. A proxy npm registry, which caches modules that are downloaded from the global registry, https://registry.npmjs.org/
  3. A group npm registry, which acts as an aggregator for the other two registries

You also need your npm registry credentials. The user ID is your email address, which doesn’t need to be known to the Nexus server, and your auth token is the base64 representation of your Nexus user ID and password. An example auth token might be echo -n nexus_user_id:nexus_password | base64 -w0 -

Try it

You can check out an example of a toolchain that builds two node modules by clicking the Create Toolchain button. You’ll need to enter your Nexus server configuration information. Also, be sure to select a reasonable org and space for Delivery Pipeline.

Create toolchain

The resulting toolchain includes two GitHub repos, a Nexus integration, and two Delivery Pipelines, one for the module and one for the app.

npmToolchain

Resources

More How-tos Stories

Using SSH tunnels and Selenium to test web applications on a continuous delivery pipeline

Developers often have a need to test their web applications. In particular they often have a need to automate these tests as part of a continuous integration (CI) pipeline. One such tool that helps facilitate this test requirement is Selenium. Selenium is a piece of software which is designed to automate browser behaviour, in that you can program it to visit a particular web page and then perform a series of actions on that web page. Most often this is leveraged to test web applications, although its functionality is not limited to that single use case. With a default configuration, however, this isn’t possible as the Selenium Server has no way of reaching an application that has been started within a CI container.

Continue reading

Integrate and Analyze Diagnostic Logs with IBM Cloud Log Analysis

Analyzing diagnostic logs, monitoring application health and keeping track of security-related events are at the foundation of successfully running apps and services. IBM Cloud offers services for that purpose. Today, I am going to show you how to use IBM Cloud Log Analysis to integrate, search and analyze as well as visualize diagnostic logs in the IBM Cloud.

Continue reading

Obey your commands: Home automation using Watson and PubNub

Integration of voice control in smart devices is buzzing, and adoption continues to grow. Voice control provides a more natural way of interacting with connected apps and devices ranging from news feeds, traffic information to acting as personal assistants in the home. These intelligent devices respond to commands spoken in our own voice and act immediately.

Continue reading