node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »


Nodeshift Build Status Coverage Status

Greenkeeper badge

Nodeshift is a Plugin for running openshift deployments for node.js projects

Disclaimer: Nodeshift is extremely experimental at the moment. This means it is under heavy development, api's could change at any time until a 1.0.0 release


To install globally: npm install -g nodeshift

or to use in an npm script

npm install --save-dev nodeshift

// inside package.json
scripts: {
  nodeshift: nodeshift

$ npm run nodeshift

Example Usage


  • Minishift

For this example, we will run against an Openshift Cluster running locally using Minishift.

There are directions here to install Minishift

I installed using Homebrew and use Virtual Box as my hypervisor provider, so my command to initially start minishift was something like this: minishift start --vm-driver=virtualbox

  • OC command line tools

These are also part of the minishift install, and step 2 of this section tells you how to put them on your path.

This guide also assumes you have a modern version(4+) of Node.js and npm installed.


For this example, we will use this very simple express based node app,

From this point on, all commands will assume you are in the directory of this source code

Notice that there is a .nodeshift directory in the project, this will hold application specific resource files for creating Routes/Serivces/DeploymentConfigs

Before running the nodeshift command, we first need to login to our Openshift Cluster running on Minishift using the oc login command

oc login -u developer for example.

Also make sure to either create a new project or change into an existing one.

Lets just create a new project for this example: oc new-project node-demo

All that is left is to run the nodeshift command.

The examples package.json has a script defined called "openshift" that will run the nodeshift command, run that like this:

$ npm run openshift

There is a file called runner.js, this makes use of the one(currently) public API called deployApplication, that can be run like so:

$ node runner.js

Or just calling nodeshift directly if you have it installed globally

$ nodeshift

Whatever is run, you will see output similiar to this:

~/s/nodejs-rest-http ❯❯❯ nodeshift  --osc.strictSSL false
2017-07-12T18:56:28.850Z INFO loading configuration
2017-07-12T18:56:28.866Z INFO using namespace nodeshift-demo at
2017-07-12T18:56:28.882Z INFO creating archive of package.json,, app.js, public, bin
2017-07-12T18:56:28.934Z INFO creating build configuration nodejs-rest-http-s2i
2017-07-12T18:56:28.952Z INFO creating image stream nodejs-rest-http
2017-07-12T18:56:28.962Z INFO uploading binary archive /usr/src/nodejs-rest-http/tmp/nodeshift/build/archive.tar
2017-07-12T18:56:31.138Z INFO binary upload complete
2017-07-12T18:56:31.138Z INFO waiting for build to finish
2017-07-12T18:56:31.192Z TRACE Receiving source from STDIN as archive ...
2017-07-12T18:56:31.399Z TRACE ---> Installing application source
2017-07-12T18:56:31.418Z TRACE ---> Building your Node application from source
2017-07-12T18:56:31.418Z TRACE ---> Using 'npm install'
2017-07-12T18:56:34.294Z TRACE added 50 packages in 2.441s
2017-07-12T18:56:34.913Z TRACE
2017-07-12T18:56:34.913Z TRACE Pushing image ...
2017-07-12T18:56:34.986Z TRACE Pushed 3/8 layers, 38% complete
2017-07-12T18:56:34.986Z TRACE Pushed 4/8 layers, 51% complete
2017-07-12T18:56:35.000Z TRACE Pushed 5/8 layers, 64% complete
2017-07-12T18:56:35.004Z TRACE Pushed 6/8 layers, 77% complete
2017-07-12T18:56:35.006Z TRACE Pushed 7/8 layers, 89% complete
2017-07-12T18:56:35.315Z TRACE Pushed 8/8 layers, 100% complete
2017-07-12T18:56:35.610Z TRACE Push successful
2017-07-12T18:56:39.139Z INFO build nodejs-rest-http-s2i-1 complete
2017-07-12T18:56:39.147Z INFO docker image repository
2017-07-12T18:56:39.171Z INFO creating deployment configuration nodejs-rest-http
2017-07-12T18:56:39.177Z INFO creating new serivce nodejs-rest-http
2017-07-12T18:56:39.178Z INFO creating new route nodejs-rest-http
2017-07-12T18:56:39.187Z INFO route host mapping
2017-07-12T18:56:39.199Z INFO done

If you login to your local Openshift cluster and navigate to the "node-demo" project, there should be a new deployment with a route to your application.

For example:

please note: Currently, once a route, service, deployment config, build config, and imagestream config are created, those are re-used. The only thing that changes from deployment to deployment is the source code. This will change in the future

.Nodeshift Directory

The .nodeshift directory is responsible for holding your resource files. These are .yml files that describe you service, deployments and routes.

Currently, nodeshift will only create resources based on the files specified, in the future, its possible somethings could be created by default

Template Parameters

Some templates might need to have a value set at "run time". For example, in the template below, we have the ${SSO_AUTH_SERVER_URL} parameter:

    apiVersion: v1
    kind: Deployment
        name: nodejs-rest-http-secured
            - env:
              - name: SSO_AUTH_SERVER_URL
                value: "${SSO_AUTH_SERVER_URL}"
              - name: REALM
                value: master

To set that using nodeshift, use the -d option with a KEY=VALUE, like this:

nodeshift -d SSO_AUTH_SERVER_URL=https://sercure-url

note that we left off the "${}" on the key, nodeshift knows to search for a key with ${} added back on

For more on writing openshift templates, see here

Advanced Options

There are a few options available on the CLI or when using the API

    Usage: nodeshift [--options]

        --version             Show version number                            [boolean]
        --projectLocation     change the default location of the project      [string]
        --configLocation      change the default location of the config       [string]
        --nodeshiftDirectory  change the default name of the directory nodeshift looks
                                at for resource files                           [string]
        --osc.strictSSL       setting to pass to the Openshift Rest Client. Set to
                                false if using a self-sign cert
        --nodeVersion, -n     the version of Node.js to use for the deployed
            [string] [choices: "latest", "8.x", "7.x", "6.x", "5.x", "4.x"] [default:
        --help                Show help                                      [boolean]


Please read the contributing guide