Dev Center

.worker Files

We like to encourage our users to think of workers as independent chunks of functionality, reusable building blocks that they can then build an application out of. .worker (pronounced dotworker) files serve to reinforce this idea, by allowing users to define their workers outside of their application code.

.worker files are pretty easy to understand: their purpose is to construct the code packages that are uploaded to the IronWorker cloud. This is done in almost precisely the same way that code packages are constructed in scripts, but .worker files can be bundled with the workers and stored in their own git repository, or moved about without any worry that unnecessary code lingers in your application, cluttering it, or that you’re missing code that it will take for your worker to run. Workers can finally be their own self-contained units.

Table of Contents

Making a Worker File

A common misconception is that .worker files are named “.worker” (e.g., ~/my_worker/.worker). This is not the case. Instead, the files are given unique names that will identify your worker in our system. So, for example, cool_worker.worker will create a worker named “cool_worker”.

Note: You should never have a file named ".worker". They should always be given a unique, recognisable name: "HelloWorld.worker", "SendMail.worker", "do_something_awesome.worker", etc.

Structure

The .worker file mirrors the code you would use to construct a package in your application. Here’s a simple example:

.worker 
runtime "ruby"
exec "hello_worker.rb"

This .worker file defines a code package that consists of a single hello_worker.rb script, which is what will be executed when your worker is run.

You can also add the files your worker is dependent upon:

.worker 
runtime "ruby"
exec "hello_worker.rb"

file "dependency.rb"
file "config.json"

That worker will have access to the dependency.rb and config.json files after it’s uploaded.

Everything you can do in your application to construct a code package, you can do in a .worker file. Here’s an example that includes a gem:

.worker 
runtime "ruby"
exec "hello_worker.rb"

file "dependency.rb"
file "config.json"

gem "mongoid"

Not only will this worker have access to dependency.rb and config.json, it will have access to the mongoid gem, as well.

Note: Gems merged with the .worker file will not be automatically required in your worker files, just as they are not when you merge gems in your application's code.

Syntax Reference

The following syntax is valid in .worker files:

Keyword Runtime Purpose Arguments
runtime all Set worker's runtime
name all Set worker's name The name to give the worker
full_remote_build all Activates full remote build mode. true or false, defaults to false
exec all Merge a file and designate it as the file to be executed when the worker is run. You may only have one file designated as the executable per worker.
  1. The path to the file
  2. The name to give the worker. Defaults to a camel-cased version of the file name will be used. (optional)
file all Merge a file into the code package.
  1. The path to the file
  2. The path the file should be stored under in the package. Defaults to the root directory. (optional)
dir all Merge an entire directory (and all its contents) into the code package.
  1. The path to the directory
  2. The path the directory should be stored under in the package. Defaults to the root directory. (optional)
deb all Merge a x86_64 deb package into the code package. Note: dependencies will not be handled. The path to the deb file
gem ruby Merge a gem with its dependencies. Note: binary extensions will not be merged, as they are not supported.
  1. The name of the gem to merge, as it appears in a require statement
  2. The version requirement for the gem. Defaults to ">= 0". (optional)
gemfile ruby Merge all the gems from the specified Gemfile.
  1. The path to the Gemfile
  2. The groups to include in the merge. Defaults to the "default" group—the top level. (optional). Example:
    gemfile 'Gemfile', 'default', 'othergroup'
jar java Merge a jar into code package. Note: it'll be available in worker's classpath. The path to jar file
pip python Merge a pip package with its dependencies.
  1. The name of the pip package to merge.
  2. The version requirement for the pip package. Defaults to latest available at pypi.