Raad v0.5.0
Raad - Ruby as a daemon lightweight service wrapper.
Raad is a non-intrusive, lightweight, simple Ruby daemon wrapper. Basically any class which implements
the start
and stop
methods, can be used seamlessly as a daemon or a normal console app.
Raad deamonizing will work the same way for both MRI Ruby and JRuby, without modification in your code.
Raad provides basic daemon control using the start/stop commands. Your code can also use the Raad logging module and benefit easy log file output while daemonized.
Installation
Gem
$ gem install raad
Bundler
Latest from github
gem "raad", :git => "git://github.com/praized/raad.git", :branch => "master"
Released gem
gem "raad", "~> 0.5.0"
Example
Create a class with a start
and a stop
method. Just by requiring 'raad', your class will be
wrapped by Raad and become daemonizable.
require 'rubygems'
require 'raad'
class SimpleDaemon
def start
Raad::Logger.debug("SimpleDaemon start")
while !Raad.stopped?
Raad::Logger.info("SimpleDaemon running")
sleep(1)
end
end
def stop
Raad::Logger.debug("SimpleDaemon stop")
end
end
- run it in console mode,
^C
will stop it, calling the stop method
$ ruby simple_daemon.rb start
- run it daemonized, by default
./simple_daemon.log
and./simple_daemon.pid
will be created
$ ruby simple_daemon.rb -d start
- stop daemon, removing
./simple_daemon.pid
$ ruby simple_daemon.rb stop
Documentation
Introduction
By requiring 'raad' in your class, it will automagically be wrapped by the Raad bootstrap code.
When running your class file with the start
parameter, Raad will call your class start
method.
The start
method should not return unless your service has completed its work or has been
instructed to stop.
There are two ways to know when your service has been instructed to stop:
- the
stop
method of your class will be called if it is defined Raad.stopped?
will return true
There are basically 3 ways to run execute your service:
- start it in foreground console mode, useful for debugging,
^C
to trigger the stop sequence
$ ruby your_service.rb start
- start it as a detached, backgrounded daemon:
$ ruby your_service.rb -d start
- stop the daemonized service by signaling it to execute the stop sequence
$ ruby your_service.rb stop
In console mode Raad logging for level :info
and up and stdout, ie puts
, will be displayed by default.
In daemon mode, Raad logging for level :info
and up will be output in your_service.log
log file and the
your_service.pid
pid file will be created.
To toggle output of all logging levels simply use the verbose -v
parameter.
Supported rubies and environments
Raad has been tested on MRI 1.8.7, MRI 1.9.2, REE 1.8.7, JRuby 1.6.4 under OSX 10.6.8 and Linux Ubuntu 10.04
Command line options
usage: ruby <service>.rb [options] start|stop
Raad common options:
-e, --environment NAME set the execution environment (default: development)
-l, --log FILE log to file (default: in console mode: no, daemonized: <service>.log)
-s, --stdout log to stdout (default: in console mode: true, daemonized: false)
-v, --verbose enable verbose logging (default: false)
--pattern PATTERN log4r log formatter pattern
-c, --config FILE config file (default: ./config/<service>.rb)
-d, --daemonize run daemonized in the background (default: false)
-P, --pid FILE pid file when daemonized (default: <service>.pid)
-r, --redirect FILE redirect stdout to FILE when daemonized (default: no)
-n, --name NAME daemon process name (default: <service>)
--timeout SECONDS seconds to wait before force stopping the service (default: 60)
-h, --help display help message
Note that the command line options will always override any config file settings if present.
-e, --environment NAME
Raad provides a way to pass an arbritary environment name on the command line. This environment name can later be retrieved in your code using the following methods:
Raad.env
will return the symbolized environment name passed on the command line.Raad.test?
will returntrue
if the enviroment name passed on the command line wastest
.Raad.development?
will returntrue
if the enviroment name passed on the command line wasdevelopment
ordev
.Raad.stage?
will returntrue
if the enviroment name passed on the command line wasstage
orstaging
.Raad.production?
will returntrue
if the enviroment name passed on the command line wasproduction
orprod
.
Example:
$ ruby your_service.rb -e foobar start
if Raad.env == :foobar
# do foobar stuff
end
if Raad.production?
# never get here
end
Custom command line options
It is possible to add custom command line options to your service, in addition to Raad own command line options. To handle custom command line options simply define a self.options_parser
class method in your service class. This method will be passed a OptionParser object into which you can add your rules plus also a Hash to set the parsed options values. The OptionParser object must be returned.
Check complete example file examples/custom_options.rb
Example:
# options_parser must be a class method
#
# @param raad_parser [OptionParser] raad options parser to which custom options rules can be added
# @param parsed_options [Hash] set parsing results into this hash. retrieve it later in your code using Raad.custom_options
# @return [OptionParser] the modified options parser must be returned
def self.(raad_parser, )
raad_parser.separator "Your service options:"
raad_parser.on('-a', '--aoption PARAM', "some a option parameter") { |val| [:aoption] = val }
raad_parser.on('-b', '--boption PARAM', "some b option parameter") { |val| [:boption] = val }
raad_parser
end
The parsed options values can later be retrieved in your code using Raad.custom_options
which will hold the Hash as set in your options_parser
class method.
do_this if Raad.[:aoption] == 'a option parameter value'
$ ruby your_service.rb -h
usage: ruby <service>.rb [options] start|stop
Raad common options:
-e, --environment NAME set the execution environment (default: development)
-l, --log FILE log to file (default: in console mode: no, daemonized: <service>.log)
-s, --stdout log to stdout (default: in console mode: true, daemonized: false)
-v, --verbose enable verbose logging (default: false)
--pattern PATTERN log4r log formatter pattern
-c, --config FILE config file (default: ./config/<service>.rb)
-d, --daemonize run daemonized in the background (default: false)
-P, --pid FILE pid file when daemonized (default: <service>.pid)
-r, --redirect FILE redirect stdout to FILE when daemonized (default: no)
-n, --name NAME daemon process name (default: <service>)
--timeout SECONDS seconds to wait before force stopping the service (default: 60)
-h, --help display help message
Your service options:
-a, --aoption PARAM some a option parameter
-b, --boption PARAM some b option parameter
Configuration and options
tbd.
Logging
Raad uses Log4r for logging and provides hooks for logging in your service. Here's an example of how to use Raad logging:
Raad::Logger.debug("this is a message with level DEBUG")
Raad::Logger.info("this is a message with level INFO")
Raad::Logger.warn("this is a message with level WARN")
Raad::Logger.error("this is a message with level ERROR")
Raad::Logger.fatal("this is a message with level FATAL")
- By default, Raad will output log messages of level
INFO
and higher. - If the
-v, --verbose
command line option is used, Raad will output all log messages (levelDEBUG
and higher).
Alternatively, the log output level can be set in your service using the Raad::Logger.level=
method. The valid levels parameter are :debug
, :info
, :warn
and :error
.
Stop sequence details
tbd.
Testing
There are specs and a validation suite which ca be run in your current ruby environment:
$ rake spec
$ rake validation
Also, specs and validations can be run in all currently tested Ruby environement. For this RVM is required and the following rubies must be installed:
- ruby-1.8.7
- ree-1.8.7
- ruby-1.9.2
- jruby-1.6.4
In each of these rubies, the gemset @raad containing log4r ~> 1.1.9
, rake ~> 0.9.2
and rspec ~> 2.6.0
must be created.
This RVM environment can be created/updated using:
$ rake rvm_setup
To launch the tests for all rubies use:
$ rake specs
$ rake validations
TODO
- better doc
- more examples
Dependencies
- For normal usage, the log4r gem (~> 1.1.9) is required.
- For testings, the rspec (~> 2.6.0), rake (~> 0.9.2) gems and RVM are required.
Author
Colin Surprenant, @colinsurprenant, [email protected], [email protected], http://github.com/colinsurprenant
Acknowledgements
Thanks to the Thin (https://github.com/macournoyer/thin), Goliath (https://github.com/postrank-labs/goliath), Sinatra (https://github.com/bmizerany/sinatra) and Spoon (https://github.com/headius/spoon) projects for providing inspiration and/or code!
License
Raad is distributed under the Apache License, Version 2.0. See the LICENSE.md file.