Accessing the web interface

If ruote-kit starts up without any issues (ie missing dependencies), you
can point your browser to 'localhost:9292/_ruote/' to get
going. By default ruote-kit binds to all IP addresses, so this works out
the box remotely too.

Plugging ruote-kit into your rack-stack

ruote-kit is fully self-sufficient piece of rack, but can be slotted into
any rack middleware stack without issues.

Example:

RuoteKit.engine = Ruote::Engine.new(
Ruote::Worker.new(
Ruote::FsStorage.new('ruote_work')))
RuoteKit.engine.register do
catchall
end
# Slot into the stack
use RuoteKit::Application

Example application

Configuring ruote-kit & ruote

ruote-kit itself needs only little configuration, the only thing to do is
to bind a ruote engine to use. That engine may be configured, see ruote.rubyforge.org/configuration.html
for details.

When using the source version, you'll have to edit the
config.ru file if you want to change the engine configuration. It
defaults to use file system persistence and runs a worker
within the engine. The persistence files will be stored in a sub directory
called “ruote_work_#{ENV}”.

When using the gem version or plugging ruote-kit into your rack stack,
you'll have to bind the ruote engine to use yourself. See the examples
above.

Registration of participants

ruote participants may be registered using the register method of the
engine. It expects a block containing of participant and one or
less catchall calls.

You may also use the catchall participant provided by ruote. It's named
'.+', so it will catch all workitems for any participant mentioned
in your workflow definitions which are not already caught by another
(previously) registered participant. So make sure to register the catchall
after your own participants. The catchall participant may be registered by
calling catchall within the block given to Ruote::Engine#register
(this will use Ruote::StorageParticipant as participant implementation, you
may use any options of Ruote::Engine#register_participant to overwrite that
default – see the example above).

Running workers

Always make sure to have a running ruote worker for
your storage. The shipped config.ru takes care of that, but if you use the
gem version or use ruote-kit as part of your rack stack, you'll need to
make sure there is a running worker.

Perhaps it's best to give some more explanations about the architecture
of ruote here. Ruote's engine class is shallow, just a few methods that
insert launch and reply orders in the storage and read it when querying for
process statuses. You see: The storage is important, it is used as
communications backend between the various parts of ruote. The engine class
and the storage are not enough, though. The real work is done by one or
more workers which query the storage for things to do (note: it is unlikely
that you will ever need more than one worker for one ruote instance; ruote
isn't fast, but it's faster than most human processes, so that
you'll won't need more than one worker unless you are running
hundreds of processes at the same time ).

That is fine, especially when there is only one instance of the app running
or the storage implementation supports multiple workers, because if there
is more than one instance of the app running, there will be more than one
worker operating on the same storage.

If you want to use a storage implementation which doesn't support
multiple workers (Ruote::FsStorage under Windows, for example), you should
start a dedicated worker in its own instance. In config.ru (or whereever
you configure the engine to be used by ruote-kit), instanciate the engine
without a worker:

ruote-kit or your rack app will start with no problems, you may even launch
processes, but they'll never show up under /_ruote/processes: There is
no worker which processes the launch requests stored in the storage.

To run a worker you need to setup a worker script similar to the rake task
example below:

Make sure to configure the storage in the same way as in the rest of the
application or you won't get what you expect ;-)

If you used the Ruby on Rails 3 template for 'installing'
ruote-kit, a ruote:run_worker task is added automatically (in
lib/tasks/ruote.rake).

You also should consider using a separate worker instance when you're
running ruote-kit or your rack app in an environment like Passenger: You
won't be sure the app runs all the time, so it's likely that
scheduled events will be missed (better: triggered too late). If you
don't want to start a separate worker process, configure Passenger in a
way that your app won't be killed in a very long time (Passenger 3
provides an option to ensure one instance of the app won't be killed)
and make sure your storage implementation supports multiple workers.

Feedback & bug reports

Feedback and bug reports are welcome on the mailing-list, or
on the #ruote IRC channel at Freenode.net.

Please do not hesitate to come back with any feedback.

License

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the
following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.