TreadMill

TreadMill Rails plugin for background workers. This gem is designed to integrate into an existing Rails application and provide immediate RabbitMQ integration using the Sneakers worker gem and Rails 4.2.0.beta1 ActiveJob.

Notes

Tags:

  • 0.0.1 tag for Rails 4.1
  • 0.0.2 tag for Rails 4.2.0.beta1
  • HEAD or 0.0.3 tag for Rails 4.2 stable

Installation

Add this line to your applications's Gemfile:

gem 'tread_mill'

And then execute:

bundle install

Usage

Options

module MyApp
  class Application < Rails::Application
    # Queues you wish to listen on.
    config.active_job.queue_name_delimiter = '.'
    config.active_job.queue_adapter = :sneakers
    config.active_job.queue_base_name = 'amqp.myapplication'

    # configure queues: amqp.myapplication.my_queue and amqp.myapplication.my_second_queue
    config.tread_mill.queues = %w(my_queue my_second_queue)

    # Configure 'ActionMailer#deliver_later': amqp.myapplication.mailers
    config.tread_mill.queues << 'mailers'

    # Optional: Probably best set in your sneakers configuration.
    # config.tread_mill.workers = # of workers

  end
end

Running your ActiveJob based workers.

rake tread_mill:run

That's it.

Example Upstart:

As suggested by jondot, the Sneakers maintainer, daemons used to run jobs with Sneakers, and thusly TreadMill, should be done so using Upstart (or whatever flavor other of daemon management subsystems your chosen OS uses). Sneakers no longer supports the ability to daemonize.

The following a sample upstart config file to get you started:

description 'Application Tread Mill Server'

env ENVIRONMENT_VAR='VALUE'

setuid deploy
setgid www-data

chdir /srv/www/application/current

start on [2345]
stop on [!2345]

exec /usr/local/bin/ruby /usr/local/bin/bundle exec rake tread_mill:run

This file will go in /etc/init on Ubuntu systems. Should be named with the service name followed by .conf: application-treadmill.conf.

Now to start/stop your service:

root@nix:/root# start application-treadmill
application-treadmill start/running, process 27996
...
root@nix:/root# stop application-treadmill
application-treadmill stop/waiting

More information on Upstart can be found here.

NOTE: Upstart restart is not the command you are looking for waves 2 fingers from left to right in front of you. You must stop/start between configuration changes for the changes to take effect.

Example workers:

Assuming you are using the ActiveJob::Base worker class:

# app/workers/my_worker.rb

# Assuming: config.active_job.queue_name_delimiter = '.'

class Workers::MyWorker < ActiveJob::Base
  queue_as :my_queue # queue used will be 'amqp.myapplication.my_queue'

  def perform(user)
    user.do_work
  end

  class << self
    def work_for(user)
      self.enqueue(user)
    end
  end
end

Then you are set to use your workers wherever you want:

# app/models/user.rb

class User
  def work_later
    Workers::MyWorker.work_for(self)
  end
end

Support Versions

Rails 4.2.0

Should be working now. If you see any issues, feel free to submit a Pull Request.

Rails 4.2.0.beta1

TreadMill should work out of the box with a valid Sneakers configuration. For ActionMailer::DeliverLater integration, all you need to do is include a :mailer queue, which should be prefixed by your selected queue_name_prefix (config.tread_mill.queues = %(amqp.myapplication.mailers)).

Rails <=4.1

Due to a pretty large set of API changes between ActiveJob's github repository pre-merge and now, it doesn't make sense to support pre-4.2 ActiveJob, especially considering the Rails team has flatly rejected supporting pre-4.2. As a result, this gem as of version 0.0.2, only supports >= 4.2.0.beta1.