IronWorkers in Node.js

This approach uses our depreciated workflow. Please see https://github.com/iron-io/dockerworker/tree/master/node for the current process.

Notice – For the NPM Certificate Error. Please use the following in your “.worker” file, instead of build "npm install":

build "npm config set strict-ssl false; npm install --production"

Node.js is an evented language that brings the well-known Javascript language to server-side development, using Google’s V8 runtime. The evented model of programming lends itself nicely to the asynchronous nature of workers, making it a natural fit for IronWorker. This article will walk you through getting your Node.js workers running on IronWorker, but you should still be familiar with the basics of IronWorker.

Quick Start

Get the CLI

We’ve created a command line interface to the IronWorker service that makes working with the service a lot easier and more convenient.

$ curl -sSL https://cli.iron.io/install | sh

Get Docker

This allows you to test your worker locally in the exact same environment as when running on the IronWorker platform using Iron.io’s public Docker images. To get started, just head to www.docker.com and download the appropriate version.

Create Your Configuration File

You’ll need a configuration file or environment variables set that tell it what your credentials are. We have some pretty good documentation about how this works, but for simplicity’s sake, just save the following as iron.json in the same directory as your JavaScript file.

{
  "project_id": "INSERT YOUR PROJECT ID HERE",
  "token": "INSERT YOUR TOKEN HERE"
}

You should insert your project ID and token into that iron.json file. Then, assuming you’re running the commands from within the folder, the CLI will pick up your credentials and use them automatically.

Write Your Node.js Worker

console.log("Hello World from Node.js.");

Accessing the Params and Config Variables.

To access the contents of the configuration and payload variables from within your worker use the following helpers we’ve included in your environment. see source for these helpers here.

var worker = require('node_helper');
console.log("params:", worker.params);
console.log("config:", worker.config);
console.log("task_id:", worker.task_id);

Test Your Code Locally

If this is your first time using these images, it may take a bit of time to download, but once their on your system, it’s lightening fast. Run the following commands:

$ docker run --rm -v "$PWD":/worker -w /worker iron/node node hello_worker.js

Upload Your Worker

Commands below will create your worker code package and upload it to the IronWorker platform. Remember, you only need to do this when you make changes to your worker code.

$ zip -r hello_worker.zip .
$ iron worker upload --zip hello_worker.zip --name hello_worker iron/images:node-4.1 nodehello_worker.js

The first command zips up everything in the current directory named hello_worker.zip.

The next command uploads the package to the Iron.io platform. That command will read your .worker file, create your worker code package and upload it to IronWorker. Head over to hud-e.iron.io, click the Worker link on your projects list, then click the Tasks tab. You should see your new worker listed there with zero runs. Click on it to show the task list which will be empty, but not for long.

Let’s quickly test it by running:

iron_worker queue hello

Now look at the task list in HUD and you should see your task show up and go from “queued” to “running” to “completed”.

Now that we know it works, let’s queue up a bunch of tasks from code. Note: Once you upload a code package, you can queue as many tasks as you’d like against it. You only need to re-upload the code package when your code changes.

Queue Up Tasks for Your Worker

Once your code has been uploaded, it’s easy to queue a task to it. It’s a single, authenticated POST request with a JSON object. This can be done through your code, or the commandline:

iron worker queue --wait hello_worker

You can also do this through your code:

var ironWorker = require('iron_worker');
 
var client = new ironWorker.Client();
 
client.tasksCreate('hello', {foo: 'bar'}, {}, function(error, body) {
  console.log(body);
});

Note: Please make sure to check out our official node client library

Deep Dive

Payload Example

Retrieving the payload in Node.js is the same as it is on any other language. Retrieve the -payload argument passed to the script, load that file, and parse it as JSON.

We’ve included a useful helper module in node to assist in retrieving the payload and configuration variables in node. Simply require the helper module and call config, params, task_id.

var worker = require('node_helper');
console.log("params:", worker.params);

// you can also access the following
console.log("config:", worker.config);
console.log("task_id:", worker.task_id);

Packaging Worker Dependencies using Node

dependencies with Node require that you create a package.json file To generate a package.json the following more info:npm init

npm-init

when adding and installing modules run then following to automatically update your package.json manifest.

npm install <module name> --save

Ensuring your script exits with the right exit code

It is important in some cases to declare a explicit exit code to give our systems a indication if your worker has completed sucessfully or failed. this also prevents instances where your worker may just hang or wait. In your worker:

process.exit(1); 
/* Task was unsuccessful */
process.exit(0); 
/* Task was successful */

Local build

requirements

• package.json with included dependencies
• /node_modules directory
• any other dependencies (files, directories, etc.)

If you’re using NPM modules within your worker, you’re going to need to package those dependencies when you upload the worker. To do this, add

dir "node_modules"

and

file "package.json"

to your .worker file:

# set the runtime language; this should be "node" for Node.js workers
runtime "node"
# exec is the file that will be executed when you queue a task
exec "hello_worker.js" # replace with your file
dir "node_modules" # include dependency files when uploading
file "package.json" # include dependency manifest when uploading

Remote build

requirements

• package.json with included dependencies

If you’re using NPM modules within your worker, you’re going to need to package those dependencies when you upload the worker. To do this, add a dir "node_modules" line and a file "package.json" line to your .worker file:

runtime "node"
exec "hello_worker.js" # replace with your file
file "package.json" # include dependency manifest when uploading
build "npm install" # run npm install
# build your dependencies remotely from package.json
remote # you can use "full_remote_build true" or shorthand "remote"