The IronWorker Command Line Tool

The Iron.io command line tool will help you interact with the IronWorker API to make creating workers easier.

Installing

The new Iron cli tool has an easy installer:

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

If you’re having issues with the above installation command, then you can use the iron/cli docker image. All the commands are the same, but instead of starting the command with iron, change it to:

docker run --rm -it -v "$PWD":/app -w /app iron/cli ...

You’ll also need Docker installed on your machine to test your workers.

You should be all set up now. To check your installation, run the following:

iron --version

Configuration

The command line tool follows the global configuration scheme that all official libraries use. You can configure the tool by creating an iron.json file in the directory of your worker, an .iron.json file in your home directory, or the environment variables. For example, to override the project ID for a single command, you could run the following:

IRON_PROJECT_ID=new_project_id_here iron worker upload --zip myworker.zip --name myworker iron/images:ruby-2.1 ruby myworker.rb

The same applies to the IRON_TOKEN environment variable.

Creating and Uploading Code Packages

Once you’ve got your worker running (see Getting Started ), you need to package it up. Packaging is simply making a zip out of your worker:

zip -r hello.zip .

To upload the worker package/zip with image from public repo:

iron worker upload --zip $WORKER.zip --name $WORKER_NAME $IMAGE $COMMAND

To upload the worker package/zip with image from private repo:

iron docker login -u USERNAME -p PASSWORD -e YOUR@EMAIL.COM

iron worker upload --zip $WORKER.zip --name $WORKER_NAME $IMAGE $COMMAND

Where $WORKER is replaced by the name of your packaged worker zip and $COMMAND is the command you want executed, the same one you used with docker run.

Sometimes, you want to limit the number of parallel workers for any given task, to prevent external resources like databases or APIs from crashing under the weight of your workers’ requests. We have a max_concurrency feature that lets you do just this. To use it, simply use the --max-concurrency option when uploading a worker, with the maximum number of workers that can be run in parallel:

iron worker upload --max-concurrency 10 ...

If you’re worried about errors, your worker is idempotent (meaning that it can be run multiple times without affecting the result), and you’d like to automatically retry your worker if it errors out, you can use the retries and retries-delay options. retries allows you to specify the maximum number of times failed tasks will be re-run:

iron worker upload --retries 5 ...

You can also optionally specify the delay between retries by using retries-delay:

iron worker upload --retries 5 --retries-delay 10 ...

There are additional options available to the upload command; you can find a list of them by running iron worker upload --help. All of these options can be mixed and matched at will to easily create very complex, specific behaviors.

Uploading Code Packages for Dockerhub-like services

This method works only for those who have dedicated cluster. Before uploading the code you need to verify that you have successfully logged in to the service:

docker login -u USERNAME -p PASSWORD -e YOUR@EMAIL.COM https://COMPANY-docker-dockerv2-local.SERVICE.com/v2/

After that, try login using ironcli:

iron docker login -u USERNAME -p PASSWORD -e YOUR@EMAIL.COM -url https://COMPANY-docker-dockerv2-local.SERVICE.com/v2/

Registry API version at the end of url /v2/ is required. We support only v2

Then upload the worker package/zip:

iron worker upload --zip $WORKER.zip --name $WORKER_NAME  COMPANY-docker-dockerv2-local.SERVICE.com/REPO-NAME:TAG-NAME $COMMAND

Uploading to Multiple Environments

It is a common and good practice to deploy applications to multiple environments, such as staging and production for quality assurance of releases. IronWorker supports workflows like this by using separate Iron.io projects, and the CLI has a convenient feature to assist.

You can set up a project for each of your desired environments (say, “MyApp Production”), then include each project in your iron.json configuration nested under an environment nickname:

{
  "production": {
    "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "project_id": "000000000000000000000001"
  },
  "staging": {
    "token": "BBBBBBBBBBBBBBBBBBBBBBBBBB",
    "project_id": "000000000000000000000002"
  },
  "development": {
    "token": "CCCCCCCCCCCCCCCCCCCCCCCCCC",
    "project_id": "000000000000000000000003"
  },
  "test": {
    "token": "DDDDDDDDDDDDDDDDDDDDDDDDDD",
    "project_id": "000000000000000000000004"
  }
}

These nicknames (production, staging) can be whatever you like, so they can be shorter than the projects’ descriptive names in the web HUD.

Now you can upload your code packages to each environment by specifying the --env option to the CLI:

iron --env test       worker upload --zip hello-rb.zip --name helloworker-rb iron/images:ruby-2.1 ruby myworker.rb
iron --env production worker upload --zip hello-js.zip --name helloworker-js iron/images:node-0.10 node myworker.js

Queuing Tasks

Testing workers no longer takes a script that creates a task to test with. Instead, you can queue tasks directly from the command line:

iron worker queue [--priority 0|1|2] [--payload '{"somekey": "some_value", "array": ["item1", "item2"]}'] $WORKER

Alternatively, you can specify a payload file, instead of providing the payload inline:

iron worker queue --payload-file /path/to/payload/file.json $WORKER

Sometimes, you want a task to be queued after a delay. You can easily do this with the --delay option:

iron worker queue --delay 60 $WORKER

The task will then be queued after the number of seconds passed to delay (one minute in the above example).

If you want to limit a task to a certain run time below our one hour max, you can do that with the --timeout option:

iron worker queue --timeout 1800 $WORKER

The task will automatically be killed after the number of seconds passed to timeout (half an hour in the above example).

There are a lot of options when you queuing tasks that can be combined to get exactly the execution you need. You can find a list of these options by running iron_worker queue --help.

Scheduling Tasks

The command line tool also allows you to schedule tasks to be run repeatedly or at a later time, just as the gem would allow you to in a script.

You can schedule a task using the following command:

iron worker schedule [--start-at "2013-01-01T00:00:00-04:00"] [--run-times 4] [--priority 0|1|2] [--payload '{"somekey": "some_value"}'] $WORKER

You can find a list of options for the command by running iron worker schedule --help.

Retrieving a Task's Log

You no longer have to write a script to check the log of your tasks. You can install call the following command:

iron worker log [OPTIONS]

You can find a list of options for the command by running iron worker log --help.