IronWorker Documentation

Offload your tasks to the parallel-processing power of the elastic cloud. Write your code, then queue tasks against it—no servers to manage, no scaling to worry about.

Check out our Post on Top 10 Use Cases for IronWorker Here!

1. Write Your Worker

IronWorker's environment is just a Linux sandbox that your task is executed in. Anything you write that runs on your machine, if packaged correctly, should be able to be run in IronWorker. For example workers, check out the examples repository or the page for your favorite language.

2. Create and Upload Your Code Package

You need to package all your code and its dependencies together and upload it to IronWorker before it can be run—your code is run entirely on IronWorker's servers, so it's important that you package all the dependencies of your code with it. There are several parts to this step, but you only need to do this when you want to update your worker's code, so you shouldn't have to do it very often.

Note: You only need to upload your code package when your code changes. Queuing tasks does not require you to upload the code package again.

The suggested way to do this is through a .worker (pronounced "dotworker") file. There's extensive documentation for .worker files, but the snippet below should be enough to get you started. Just save it as "firstworker.worker" in the same directory as your code.

firstworker.worker
runtime "ruby" # The runtime the code should be run under: ruby, python, php, or sh

exec "path/to/file.rb" # The file to execute when a task is queued. Your worker's entry point

file "config.json" # The path to a file to upload as a dependency of the worker; just leave this out if you don't have any dependencies.

Note: You should never have a file named just ".worker". Always use a unique, recognisable name—it's what your code package will be named. "helloworld.worker" will create a code package named "helloworld", "turnintoaunicorn.worker" will create a code package named "turnintoaunicorn", etc.

Once you've defined your worker and its dependencies with a .worker file, you can upload it using the command line tool for IronWorker. Note: You'll need to have Ruby 1.9+ installed to use the IronWorker CLI. After that, just run "gem install iron_worker_ng" to get the tool.

To interact with the IronWorker API, you'll need your project's ID and an auth token from the HUD. Once you retrieve them, you need to configure the CLI to use them. Create an iron.json file in the same folder as your firstworker.worker file that looks like this:

iron.json
{
  "project_id": "INSERT YOUR PROJECT ID HERE",
  "token": "INSERT YOUR AUTH TOKEN HERE"
}

Once that's done, you can just run the following command:

Command Line
$ iron_worker upload firstworker

That will upload the code package to IronWorker and name it "firstworker"—you'll use the name to queue tasks to the package. That's it, your code is ready to be run!

3. Queue/Schedule Your Task

Now that you've uploaded your worker, you can just queue tasks against it to run them, in parallel, in the cloud. You can queue a task directly from your favorite language or from the command line:

Command Line
$ iron_worker queue firstworker

You can also specify a payload, which is a string that will be supplied to your worker while it runs the task, letting you pass in information. Almost all payloads are JSON strings:

Command Line
$ iron_worker queue firstworker -p '{"key1": "val1", "obj1": {"key2": "val2"}, "arr1": ["item1", "item2"]}'

Most clients—including the CLI—will automatically handle parsing the payload in your worker, so you can just access the variable or function they give you in your worker's code. We have more information on payloads, if you're curious.

Protip: we also offer a webhook endpoint—it's great for automating tasks. Check out our blog post for more information on this.

Sometimes you want tasks that repeat periodically, or that will be queued (queued, not executed) at a specific time or even date. IronWorker supports scheduled tasks for this purpose. They're just like regular tasks (payloads, executed in the cloud, in parallel), but they're queued on your schedule.

Again, you can schedule a task from your favorite language or from the command line:

Command Line
$ iron_worker schedule firstworker --start-at "2012-07-19T23:51:00-04:00"

If you want to just start a task after a short delay, you can do that too. Just specify --delay followed by the number of seconds the task should be delayed.

Command Line
$ iron_worker schedule firstworker --delay 120

If you want to have a task repeat, you can just specify the --run-every option, followed by the number of seconds between each run:

Command Line
$ iron_worker schedule firstworker --run-every 60

There are a lot of options to configure scheduling tasks; check our more detailed guide to see more of the options.

4. Inspect Your Worker (Logging)

Logging to STDOUT (default)

In a perfect world, your workers would just work. Sometimes though, workers have bugs in them or an API is down or something goes wrong. In these situations, it's helpful to have some debugging tools.

To aid in debugging, everything that is printed to STDOUT (everything from puts or print or echo or your language's equivalent) in a worker is logged in the HUD.

Also, in case you think your package wasn't built correctly or forget which version of your worker is running, the HUD offers downloads for every revision of every code package you upload.

Logging to External Services

Sometimes it is more helpful to have all logs in one place. Say you have a big web application and want to consolidate the logs of all your tasks and run global searches. We make that super simple to do. Read this blog article on how to setup real-time remote logging to external services. In the article, Papertrail is used as an example but you can send your log output to any syslog endpoint and see it in real-time. You can run your own syslog server with something like syslogd or Splunk, or you can use popular logging services such as Papertrail or Loggly.

Next Steps

You should be well-grounded in the IronWorker paradigm now—now you need to build something cool! Check out our language documentation or reference material to explore the boundaries of IronWorker's system. If you're looking for ideas about what you can accomplish with IronWorker, you may want to check out our solutions.