merge_gem

Workers run in a Ruby environment in the cloud. A limited number of gems are included as part of the native environment. See System Gems for the list.

You can merge gems (and specific gem versions) with your worker by using the merge_gem command.

Here's how:

Add merge_gem "gem_name" in your worker class (inside the class but outside the run method).

For example, to use the dropbox gem, simply add:

class DropBoxGem < IronWorker::Base
    merge_gem "dropbox"
    merge_gem "some_other_gem"

    def run
      # your worker code
    end
end

For some gems, a require might be needed:

merge_gem 'actionpack', :require => 'action_pack'

For including a specific version of a gem, just include the version number after the gem.

merge_gem "some_other_gem_with_version", "1.2.3"

For gems with different sub-directory names, include a require with the path.

merge_gem 'mongoid_i18n', :require => 'mongoid/i18n'

You can use an array of files to require on with merge_gem too:

merge_gem 'devise', :require => ['devise', 'devise/active_record/orm'] 

Merging Gems with Data Files

For including non .rb files with the gem, you can include the directory after the gem

merge_gem 'prawn', :include_dirs=>['data']

Best Practices

We recommend that you merge in the language libraries you need and not rely on the libraries or gems within IronWorker (except in the case of binary gems). These libraries may change or be different versions than you need and so it's best to isolate your dependencies as much as possible.

Unmerging Gems

In some situations you may receive errors with respect to system gems. In these cases, you made need to unmerge it. One reason for this is because it could be a binary gem and with the auto-merging of dependencies, binary gems might be loaded but not able to execute within IronWorker. (Many binary gems are included in the IronWorker system for just this reason.)

unmerge_gem 'nokogiri'

Global merge_gem

You can also specify gems that you would like to use globally. In your configuration block you can use:

config.merge_gem 'mini_fb'

This will then be used in all of your workers.

Gems with Dependencies

Gems with other gem dependencies will not automatically be merged. You may have to merge in the dependent gems in these situations. Use the gem dependency 'gem_name' command to find additional gems you may need to merge.

Also, if one gem depends on another at require/load time, then they will need to appear in the correct order. One way to think of merge_gem is as if it were just a require.

For example, if you're using the gdocs4ruby gem, running gem dependency gdocs4ruby shows that it depends ongdata4ruby.

$ gem dependency gdocs4ruby
Gem gdocs4ruby-0.1.2
  gdata4ruby (>= 0.1.1, runtime)

Given this dependency, you'll want to merge them both into your worker -- in the order of dependency.

merge_gem "gdata4ruby"
merge_gem "gdocs4ruby"

You can do multiple requires on with merge_gem.

merge_gem 'em-synchrony', :require=>['em-synchrony', 'em-synchrony/em-http',  ...]

The above (with the full set of files below) would be equivalent to doing individual requires:

require "em-synchrony"
require "em-synchrony/em-http"
require "em-synchrony/fiber_iterator"
require "em-synchrony/mysql2"
require "em-synchrony/activerecord"

System Gems/Gems with Binary Encodings

Gems that make use of binary encodings may have issues running within IronWorker. We've included a number of binary gems within the system environment. Check the Systems Gem page for the full list. Contact us if you are are making heavy use of a binary gem and would like us to include it.

To make use of a system gem, you would just need to require it.

require 'nokogiri'

Other Notes

We recommend you merge the gems you need and not do a require of them, if at all possible. Our initial policy was to support a host of popular gems but we found it wasn't the right approach. We have since moved to maintaining a more streamlined native IronWorker environment. (We were introducing some unintended conflicts and versioning issues and realized it was better to keep things simple and let users have more control.)

Gems are uploaded the first time a worker runs (and if the worker changes) but are stored in the cache for subsequent runs. If you change a gem or a merged file, make sure you modify the worker so as to force an reupload of the merged file.

The Code tab in your Dashboard will provide you with a view of the code, models, and gems that have been uploaded to IronWorker. Use this if you have questions about what gems are being merged in.