clone 1.0.0.alpha → 1.0.0.beta

data/samples/rack/init/docs/rack/webservers/ebb

@@ -0,0 +1,72 @@
+(this is only for HEAD - old docs are found in the git repo)
+
+# A Web Server Called *Ebb*
+
+Ebb aims to be a small and fast web server specifically for hosting
+dynamic Ruby language web applications.
+
+It is a binding to [libebb](http://tinyclouds.org/libebb)
+
+## Install
+
+The Ruby binding is available as a Ruby Gem. It can be install by executing
+
+    gem install ebb
+
+If you want SSL support you must install GnuTLS.
+Ebb has no other dependencies.
+
+## Running
+
+Use Ebb.start_server()
+
+## Speed
+
+(these stats are out of date)
+
+Because Ebb handles most of the processing in C, it is able to do work
+often times more efficiently than other Ruby language web servers.
+
+![Benchmark](http://s3.amazonaws.com/four.livejournal/20080311/ebb.png)
+
+Ebb-Ruby can handle threaded processing better than the other 'evented'
+servers. This won't be of any benefit to Rails applications because Rails
+places a lock around each request that wouldn't allow concurrent processing
+anyway. In Merb, for example, Ebb's thread handling will allow Ebb instances
+to handle larger loads. [More](http://four.livejournal.com/848525.html)
+
+## Contributions
+
+Contributions (patches, criticism, advice) are very welcome!
+Please send all to to
+[the mailing list](http://groups.google.com/group/ebbebb).
+
+The source code is hosted [github](http://github.com/ry/ebb/tree/master). It
+can be retrieved by executing
+
+    git clone git://github.com/ry/ebb.git
+
+## (The MIT) License
+
+Copyright (c) 2008 [Ryah Dahl](http://tinyclouds.org) (ry at tiny clouds dot org)
+
+<div id="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.
+</div>

data/samples/rack/init/docs/rack/webservers/fcgi

@@ -0,0 +1,103 @@
+fcgi - FastCGI library for Ruby
+Version 0.9.0
+
+Depends
+
+C version
+
+* ((<libfcgi|URL:http://www.fastcgi.com/#TheDevKit>))(FastCGI Developer's Kit)
+Pure Ruby Version
+
+* StringIO
+Install
+
+$ gem install fcgi
+  (Pure Ruby Version: gem install fcgi -- --without-ext)
+  (With custom FCGI lib paths: gem install fcgi -- --with-fcgi-include=/usr/local/include --with-fcgi-lib=/usr/local/lib)
+Usage
+
+Class Method
+
+— FCGI.accept
+
+Returns FCGI instance
+— FCGI.each
+
+— FCGI.each_request
+
+— FCGI.is_cgi?
+
+— FCGI.each_cgi
+
+Automatically detects whether this program is running under the FastCGI
+environment, and generates a 'CGI' type object for each request. Also
+installs signal handlers for graceful handling of SIGPIPE (which may
+occur if a client gives up on a request before it is complete) and
+SIGUSR1 (generated by Apache for a 'graceful' exit)
+
+If you are using the HTML output methods you can also pass the HTML type
+e.g. FCGI.each_cgi('html3') do ... end
+
+However, you should beware that the CGI library is quite slow when
+used in this way, as it dynamically adds a large number of methods
+to itself each time a new instance is created.
+Instance Method
+
+— FCGI#finish
+
+Finish
+— FCGI#in
+
+Returns Stream or StringIO
+— FCGI#out
+
+Returns Stream or StringIO
+— FCGI#err
+
+Returns Stream or StringIO
+— FCGI#env
+
+Returns Environment(Hash)
+Sample
+
+Using the FastCGI native interface:
+
+#!/usr/bin/ruby
+require "fcgi"
+
+FCGI.each {|request|
+  out = request.out
+  out.print "Content-Type: text/plain\r\n"
+  out.print "\r\n"
+  out.print Time.now.to_s
+  request.finish
+}
+Using the CGI-compatible interface, which works both as a standalone CGI and under FastCGI with no modifications:
+
+#!/usr/bin/ruby
+require "fcgi"
+
+FCGI.each_cgi {|cgi|
+  name = cgi['name'][0]
+  puts cgi.header
+  puts "You are #{name} " if name
+  puts "Connecting from #{cgi.remote_addr}"
+}
+Note: you can’t reference CGI environment variables using ENV when under FastCGI. It is recommended that you use the CGI-generated methods, e.g. cgi.remote_addr as above.
+
+If you need to access environment variables directly, perhaps extra ones set in your Apache config, then use cgi.env_table[‘REMOTE_ADDR’] instead. This isn’t quite as portable because env_table is a private method in the standard CGI library.
+
+License
+
+((<URL:www.ruby-lang.org/ja/LICENSE.txt>)) (Japanese)
+
+((<URL:www.ruby-lang.org/en/LICENSE.txt>)) (English)
+
+Copyright
+
+fcgi.c     0.1   Copyright (C) 1998-1999  Network Applied Communication Laboratory, Inc.
+           0.8   Copyright (C) 2002 MoonWolf <moonwolf@moonwolf.com>
+
+fastcgi.rb 0.7   Copyright (C) 2001 Eli Green
+fcgi.rb    0.8   Copyright (C) 2002 MoonWolf <moonwolf@moonwolf.com>
+fcgi.rb    0.8.5 Copyright (C) 2004 Minero Aoki

data/samples/rack/init/docs/rack/webservers/mongrel

@@ -0,0 +1,74 @@
+= 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 an Ragel extension to provide fast, accurate HTTP 1.1 protocol parsing. This makes the server scream without too many portability issues.
+
+See http://mongrel.rubyforge.org for more information.
+
+== License
+
+Mongrel is copyright 2007 Zed A. Shaw and contributors. It is licensed under the Ruby license and the GPL2. See the include LICENSE file for details.
+
+== Quick Start
+
+The easiest way to get started with Mongrel is to install it via RubyGems and then run a Ruby on Rails application. You can do this easily:
+
+ $ gem install mongrel
+
+Now you should have the mongrel_rails command available in your PATH, so 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:
+
+ $ 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.
+
+== 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.*
+
+== Contact
+
+E-mail the Mongrel list at http://rubyforge.org/mailman/listinfo/mongrel-users and someone will help you. Comments about the API are welcome.

data/samples/rack/init/docs/rack/webservers/passenger

@@ -0,0 +1,37 @@
+A modern web server and application server for Ruby,
+Python and Node.js, optimized for performance,
+low memory usage and ease of use.
+
+
+
+Phusion Passenger: a fast and robust web server and application server for Ruby, Python and Node.js
+Phusion Passenger is a web server and application server, designed to be fast, robust and lightweight. It runs your web apps with the least amount of hassle by taking care of almost all administrative heavy lifting for you. Advanced administration tools allow you to gain deep insight into your web applications' operations and to keep your servers healthy. Phusion Passenger is polyglot by design, and currently supports Ruby (Rack), Python (WSGI) and Node.js.
+
+Regular installation
+
+You can install either Phusion Passenger for Apache or for Nginx. Run either of the following programs as root:
+
+./bin/passenger-install-apache2-module
+-OR-
+
+./bin/passenger-install-nginx-module
+That's it. :)
+
+For troubleshooting, configuration and tips, please read the corresponding Users Guide:
+
+doc/Users guide Apache.html
+doc/Users guide Nginx.html
+These files are included in the source tarball, and may also be viewed online on our website.
+
+Installing as a gem
+
+gem build passenger.gemspec
+gem install passenger-x.x.x.gem
+Further reading
+
+The doc/ directory.
+CONTRIBUTING.md.
+https://www.phusionpassenger.com/support
+Legal
+
+Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.

data/samples/rack/init/docs/rack/webservers/scgi

@@ -0,0 +1,188 @@
+= ruby-scgi
+
+ruby-scgi is a Ruby library for running Ruby on Rails (and possibly other
+web applications) for high-speed deployment of your applications in production.
+It is intended as a replacement for the ancient FastCGI code base and bring
+some big advantages to Rails deployment for production operations.
+
+SCGI (Simple Common Gateway Interface) is a project to replace CGI and FastCGI
+with a simpler protocol to both implement and manage. It was written by Neil
+Schemenauer and adopted by many Python developers as a hosting option.
+
+ruby-scgi is distributed as a gem, and can be installed with:
+
+    sudo gem install scgi
+
+Feedback/Bugs/Support Requests should be handled through RubyForge at
+http://rubyforge.org/projects/scgi/.
+
+The RDoc is available at http://scgi.rubyforge.org
+Source control access is available at github
+(http://github.com/jeremyevans/ruby-scgi).
+
+== Advantages
+
+* Same performance as FastCGI and better performance than other methods.
+* Can be used to run Rails with style (sudo gem install style)
+* Gives out limited status information to help manage your application's
+  resources.
+* You can set a maximum concurrent connections limit, which causes any
+  connections over the limit to get redirected to a /busy.html file. This can
+  help keep your site alive under heavy load.
+* Simple to configure with your web server.
+* Completely free code licensed under Rails's own license.
+* No external dependencies other than Ruby
+
+== Comparison With FastCGI
+
+SCGI and FastCGI have similar goals:  To keep Ruby running between requests and
+process the requests as fast as possible.  The difference is that SCGI is much
+simpler and easier to implement so there's less chance to get it wrong.
+
+Specifically, ruby-scgi is written in pure Ruby so it doesn't leak memory,
+runs everywhere, and is easy to install (no compilers needed).
+
+One thing that SCGI doesn't support is using UNIX Domain sockets in addition to
+TCP/IP sockets.  This isn't really needed, but it is handy in a shared hosting
+situation where you don't want others connecting to your processes or if you
+have to request open ports.  Sorry, no UNIX Domain sockets in SCGI.
+
+== Comparison With WEBrick
+
+In theory WEBrick should be able to run just as fast as ruby-scgi.  They are
+both written in pure Ruby.  They both do similar processing (although WEBrick's
+are a little more complicated).  They both return about the same amount of
+data.
+
+In practice WEBrick in production mode runs much slower than ruby-scgi in
+production mode.  The (dis)advantage (depending on your point of view) is that
+you have to manage your webserver differently than you manage your application.
+
+== Comparison With CGI
+
+CGI is where every time a request comes in for rails the whole Ruby on Rails
+framework is loaded.  This is very slow, but it's easy to install.
+
+An alternative is to use the cgi2scgi program distributed with the SCGI source
+available from http://www.mems-exchange.org/software/scgi/ along with the
+Apache modules.  This program basically is a small little C program that runs
+quickly as a CGI, but passes it's requests to your ruby-scgi backend.  It's not
+all that fast, but if you're stuck with cgi-bin only access then this might be
+just the way to go.  Since SCGI runs over TCP/IP you can even host your
+ruby-scgi on a totally different machine with this.
+
+== Running and Configuration
+
+ruby-scgi is now just a library and doesn't come with a tool to run Rails. The
+previous command line tool (scgi_ctrl) has been greatly enhanced and is now
+available as a standalone gem called ruby-style.
+
+== Example configurations
+
+Note that ruby-scgi is only tested on Lighttpd.  Also, note that Lighttpd
+1.4.16 has a bug which breaks redirects using server.error-handler-404, so
+either use mod_magnet, use 1.4.18, or apply the patch in ticket 1270 on
+Lighttpd's Trac.
+
+Lighttpd:
+
+ server.modules = ( ... "mod_scgi" ... )
+ server.error-handler-404 = "/dispatch.scgi"
+
+ # For Single Process or Single-Port Clustering
+ scgi.server = ( "dispatch.scgi" => (
+    "server1" => (
+        "host" => "127.0.0.1",
+        "port" => 9999,
+        "check-local" => "disable",
+        "disable-time" => 0)
+    ))
+
+ # For Multi-Port Clustering
+ scgi.server = ( "dispatch.scgi" => (
+    "server1" => (
+        "host" => "127.0.0.1",
+        "port" => 9997,
+        "check-local" => "disable",
+        "disable-time" => 0),
+    "server2" => (
+        "host" => "127.0.0.1",
+        "port" => 9998,
+        "check-local" => "disable",
+        "disable-time" => 0),
+    "server3" => (
+        "host" => "127.0.0.1",
+        "port" => 9999,
+        "check-local" => "disable",
+        "disable-time" => 0)
+    ))
+
+Apache:
+
+ <VirtualHost your-ip:80>
+    AddDefaultCharset utf-8
+    ServerName www.yourdomain
+    DocumentRoot /your-switchtower-root/current/public
+    ErrorDocument 500 /500.html
+    ErrorDocument 404 /404.html
+    # handle all requests throug SCGI
+    SCGIMount / 127.0.0.1:9999
+    # matches locations with a dot following at least one more characters,
+    # that is, things like   *,html, *.css, *.js, which should be delivered
+    # directly from the filesystem
+    <LocationMatch \..+$>
+        # don't handle those with SCGI
+        SCGIHandler Off
+    </LocationMatch>
+    <Directory /your-switchtower-root/current/public/>
+        Options +FollowSymLinks
+        Order allow,deny
+        allow from all
+    </Directory>
+ </VirtualHost>
+
+== Changes from version 0.9.0
+
+* The library should now run on Windows, though there may be issues shutting
+  it down.
+
+== Changes from version 0.8.0
+
+* You can pass a socket to SCGI::Processor.new via settings[:socket]
+* You can have a socket created for you in new if you pass
+  settings[:host] and settings[:port]
+* You can pass an existing logger to new via settings[:log]
+* Passing a socket to listen is now optional, if you passed a socket or
+  had one created in new
+* Improved RDoc for new
+* Most SCGI::Processor methods are now private
+* SCGI::Processor is easier to subclass because it will use preexisting
+  instance variables
+
+== Changes from version 0.7.0
+
+* Command line tool is now in a seperate gem called ruby-style
+* You now must pass a socket to SCGI::Processor#listen
+* SCGI::Processor's @log and @maxconns now have defaults
+* SCGI::Processor's @host and @port are no longer used
+
+== Changes from SCGI Rails Runner by Zed Shaw
+
+* Single-port clustering is back
+* scgi_ctrl is fully configurable on the command line
+* Clustering and processing are now built into scgi_ctrl
+* DRb, Win32, and throttling are no longer supported
+* Soft reconfiguration has changed (no SIGUSR1)
+* Restarting via SIGHUP is only supported in supervise mode
+* The only commands available to scgi_ctrl are start, stop, and restart
+
+== FAQ
+
+Q: Have you been living under a rock for the last two years?  Mongrel/Nginx is
+the new hotness!
+
+A: Well, aren't you snotty.  You can certainly use Mongrel if you want.  The
+memory/performance differences are small, and it is probably better maintained.
+ruby-scgi is a simpler version of SCGI Rails Runner, and may be useful for
+certain legacy setups.  Also, it works well and it's been working for me for
+the last few years.