Getting Started With IronWorker

IronWorker is a container based distributed work-on-demand platform. We use Docker’s container format, and have container images for the major languages you can use to run your custom code. But because we use Docker you could use any available Docker image to run your custom code.

This getting started tutorial will walk you through the steps of writing custom code, testing it locally, deploying it to Iron, and queuing message to run tasks.

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.

1 Write and Test your Worker
2 Package and Upload your Worker
3 Queue Tasks for your Worker

Before you begin

Before starting, you will need to setup a couple of things. You only need to do this once.

  1. Install the Iron’s CLI tool
  2. Setup your Iron.io credentials
  3. Install Docker

Hello World Worker

This is a very simple hello world example worker in Ruby. You do not even need Ruby installed to try this example so give it a go! All languages follow the same process so you will get an idea of how things work regardless.

1. Write your custom Worker code

Create a file called helloworld.rb containing:

puts "Hello World!"

Now let’s run it in one of the Iron stack containers:

docker run --rm -it -v "$PWD":/worker -w /worker iron/ruby ruby helloworld.rb

The fact that it runs means it’s all good to run on IronWorker, so lets upload it and queue up a task for it so it runs on the IronWorker platform.

Let’s package it up inside a Docker image. You should have account on Docker Hub for this. Copy the Dockerfile from our repository and modify the ENTRYPOINT line to run your script. Build your docker image:

FROM iron/ruby

WORKDIR /app
ADD . /app

ENTRYPOINT ["ruby", "helloworld.rb"]

Build a docker image:

docker build -t USERNAME/hello:0.0.1 .

The 0.0.1 is the version which you can update whenever you make changes to your code.
USERNAME is your username on Docker Hub. Test your image, just to be sure you created it correctly:

docker run --rm -it USERNAME/hello:0.0.1

Push it to Docker Hub and register your image with Iron:

docker push USERNAME/hello:0.0.1
iron register USERNAME/hello:0.0.1

And finally queue up a job for it!

iron worker queue --wait USERNAME/hello

The --wait parameter waits for the job to finish, then prints the output. You will also see a link to HUD where you can see all the rest of the task details along with the log output.

That’s it, you have ran a worker on the IronWorker cloud platform!

Now let’s get into more detail.

2. Test your Worker

IronWorker’s environment is a Linux Docker container that your task is executed in. Anything you write that runs inside of our published Docker images should run just the same as on IronWorker. The key here is getting it to run with the Docker commands below and sample payloads.

The primary Docker command is:

docker run --rm -v "$(pwd)":/worker -w /worker IMAGE[:TAG] 'MY_COMMAND -payload MY_PAYLOAD.json'
  • Replace IMAGE with the name of the image you want your code to be executed in. For example, if your worker is a Ruby script, you can replace IMAGE with iron/ruby. Also you may need to specify a TAG (version) of the image you want to use: iron/ruby:2.2
  • Replace MY_COMMAND with what you would like to execute. For instance, if your worker was a Ruby script called myworker.rb, you would replace MY_COMMAND with ruby myworker.rb. If it was a Go program, you would change it to ./myworker.
  • Replace MY_PAYLOAD with the name of an example payload file to test with. This payload file is the format that you will use to queue up jobs/tasks for your worker after it’s uploaded.

This command may seem simple at first glance, but the main thing is that it will force you to vendor all your dependencies along with your worker. You’ll find links to an example repository showing how to do this for various languages.

3. Package your Worker

Let’s package it up inside a Docker image and upload it to a Docker Registry. Copy the Dockerfile from appropriate directory (depending on used programming language) of this repository and modify the ENTRYPOINT line to run your script. Build your docker image:

docker build -t USERNAME/IMAGENAME:0.0.1 .

That’s just a standard docker build command. The 0.0.1 is the version which you can update whenever you make changes to your code. Change USERNAME to your Docker Hub username and change IMAGENAME to your docker image name.

Test your image, just to be sure you created it correctly:

docker run --rm -it -e "PAYLOAD_FILE=MY_PAYLOAD.json" -e "YOUR_ENV_VAR=ANYTHING" USERNAME/IMAGENAME:0.0.1

4. Push it to Docker Hub

Push it to Docker Hub:

docker push USERNAME/IMAGENAME:0.0.1

5. Register your image with Iron

Ok, we’re ready to run this on Iron now, but first we have to let Iron know about the image you just pushed to Docker Hub.

iron register USERNAME/IMAGENAME:0.0.1

6. Queue / Schedule jobs for your image

Now you can start queuing jobs or schedule recurring jobs for your image.

iron worker queue --payload-file MY_PAYLOAD.json --wait USERNAME/IMAGENAME

Notice we do not use the image tag when queuing, this is so you can change versions without having to update all your code that’s queuing up jobs for the image.

The –wait parameter waits for the job to finish, then prints the output. You will also see a link to HUD where you can see all the rest of the task details along with the log output.

Of course, in practice you will be queuing up jobs via the API, most likely using one of our client libraries.

Private images

If you want to keep your code private and use a private Docker repository, you just need to let Iron know how to access your private images. From the same directory as your iron.json file, run:

iron docker login -e YOUR_DOCKER_HUB_EMAIL -u YOUR_DOCKER_HUB_USERNAME -p YOUR_DOCKER_HUB_PASSWORD

Then just do everything the same as above.

Deploying your code directly to Iron.io without docker

1. Write and Test your Worker

Stays exactly the same, Click Here to read.

2. Package and Upload your Worker

Packing is pretty straightforward knowing that you got it working with the docker run command above, just zip it up.

zip -r myworker.zip .

Then upload the zip you just created. You’ll notice this command needs you to specify a Docker Image even though you are not using Docker. This is because Iron will still execute your task in a container and needs this information to properly run:

iron worker upload [--zip myworker.zip] --name myworker DOCKER_IMAGE [COMMAND]

3. Queue Tasks for your Worker

Now you get to queue up tasks/jobs for your Worker!

iron worker queue --wait myworker

Typically you would use the IronWorker API to actually queue up tasks from other systems. The cli queue command above is primarily for testing purposes.