puma--puma/README

= Mongrel:  Simple Fast Mostly Ruby Web Server

Mongrel is a small library that provides a very fast HTTP 1.1 server for Ruby
web applications.  It is not particular to any framework, and is intended to
be just enough to get a web application running behind a more complete and robust
web server.

What makes Mongrel so fast is the careful use of a C extension to provide fast
HTTP 1.1 protocol parsing and fast URI lookup.  This combination makes the server
scream without too many portability issues.

== Status

Mongrel 0.3.9 now supports a fancy RubyGems based plugin system called GemPlugin.
It uses the basic machinery of RubyGems to implement dynamically loaded plugins
based on dependencies.  Writing a plugin is pretty easy, but right now it's
not as well documented as it should be.  There is a simple example plugin 
for adding a status command to your mongrel.  Just do:

 > gem install mongrel_status

And you'll then get a new status command.  Then just do:

 > cd myrailsapp
 > mongrel_rails start -d
 > mongrel_rails status

And it'll print out the PID your Rails app is running under.

The GemPlugin project is a sub-project of Mongrel, but it's licensed under
the Ruby license and is usable outside Mongrel


== Quick Start

After you've installed (either with gem install mongrel or via source) you should
have the mongrel_rails command available in your PATH.  Then you just do the following:

 > cd myrailsapp
 > mongrel_rails start

This will start it in the foreground so you can play with it.  It runs your application
in production mode.  To get help do:

 > mongrel_rails start -h 

Finally, you can then start in background mode (probably won't work in win32):

 > mongrel_rails start -d

And you can stop it whenever you like with:

 > mongrel_rails stop

All of which should be done from your application's directory.  It writes the
PID of the process you ran into log/mongrel.pid.

There are also many more new options for configuring the rails runner including
changing to a different directory, adding more MIME types, and setting processor
threads and timeouts.


=== Win32 Service Support

Mongrel now has support for running as a Win32 service right out of the
box.  The support is still rough but works well enough that we decided
to release it.  You can thank Luis Lavena for working on this and making
it so nice.

After you do the gem install, find a Rails application you want to run
and do:

 $ mongrel_rails_service install -n myapp \ 
     -r c:\my\path\to\myapp -p 4000 -e production
 $ mongrel_rails_service start -n myapp

Now hit the port and poof, works.  

Stopping a service is simple:

 $ mongrel_rails_service stop -n myapp

If you run into an app that's not running right, my suggestion is to run it with
the regular mongrel_rails runner:

 $ cd c:\my\path\to\myapp
 $ mongrel_rails start -p 4500

Since that will spit out error messages and stuff to the console.  *Use CTRL-Pause/Break to stop.*

Best thing about the win32 support is that you can simply use the Windows Services
in Control Panel->Admin Tools to work with it.  You can also install the same
Rails app as different installs.  For example I've got myapp_dev, and myapp_prod and
just start/stop which one I want to work with.

== Install

It doesn't explicitly require Camping, but if you want to run the examples/camping/
examples then you'll need to install Camping 1.2 at least (and redcloth I think).  
These are all available from RubyGems.

The library consists of a C extension so you'll need a C compiler or at least a friend
who can build it for you.

Finally, the source includes a setup.rb for those who hate RubyGems.


== Usage

The examples/simpletest.rb file has the following code as the simplest
example:

 require 'mongrel'

 class SimpleHandler < Mongrel::HttpHandler
    def process(request, response)
      response.start(200) do |head,out|
        head["Content-Type"] = "text/plain"
        out.write("hello!\n")
      end
    end
 end

 h = Mongrel::HttpServer.new("0.0.0.0", "3000")
 h.register("/test", SimpleHandler.new)
 h.register("/files", Mongrel::DirHandler.new("."))
 h.run.join

If you run this and access port 3000 with a browser it will say
"hello!".  If you access it with any url other than "/test" it will
give a simple 404.  Check out the Mongrel::Error404Handler for a 
basic way to give a more complex 404 message.

This also shows the DirHandler with directory listings.  This is still
rough but it should work for basic hosting.  *File extension to mime
type mapping is missing though.*


== Speed

Like previous releases 0.3.1 continues the trend of making things
as fast as possible.  It currently might be a little slower than
other releases but should hold up pretty good against at least 
WEBrick (especially when running Rails).

As before you can control the number of processor threads (and thus
ActiveRecord database connections) with:

 h = Mongrel::HttpServer.new("0.0.0.0", "3000", 40)

Which will make 40 thread processors.  Right now the optimal setting is up in
the air, but 20 seemed to be about the sweet spot on my systems.  The 
limited processors also means that you can use ActiveRecord as-is and it will
create a matching database connection for each processor thread.  More on 
this in future releases.


== Contact

E-mail zedshaw at zedshaw.com and I'll help.  Comments about the API are welcome.