From 66180ed0db386ebb5f419e8eb9bffcf446a65bcb Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Wed, 18 Mar 2009 20:05:19 -0700 Subject: Documentation updates, prepare for 0.2.0 --- CHANGELOG | 4 ++++ CONTRIBUTORS | 47 ++++++++++++++++++++++---------------- DESIGN | 3 ++- README | 73 ++++++++++++++++++++++++++++++++++++++++++++++++------------ 4 files changed, 93 insertions(+), 34 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 3cc5d62..37ef742 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,5 +1,9 @@ +v0.2.0 - unicorn_rails launcher script. + v0.1.0 - Unicorn - UNIX-only fork of Mongrel free of threading +-- old Mongrel changelog -- + v2.0. (WIP) Rack support. v1.1.4. Fix camping handler. Correct treatment of @throttle parameter. diff --git a/CONTRIBUTORS b/CONTRIBUTORS index ac47dfb..5a6fa4d 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -1,20 +1,29 @@ -Unicorn would not be possible without Zed and all the contributors to Mongrel. +Unicorn developers: +* Eric Wong +* ... (help wanted) -Eric Wong -Ezra Zygmuntowicz -Zed A. Shaw -Luis Lavena -Wilson Bilkovich -Why the Lucky Stiff -Dan Kubb -MenTaLguY -Filipe Lautert -Rick Olson -Wayne E. Seguin -Kirk Haines -Bradley Taylor -Matt Pelletier -Ry Dahl -Nick Sieger -Evan Weaver -Marc-André Cournoyer +We would like to thank following folks for helping make Unicorn possible: + +* Ezra Zygmuntowicz - for helping Eric decide on a sane configuration + format and reasonable defaults. +* Christian Neukirchen - for Rack, which let us put more focus on the server + and drastically cut down on the amount of code we have to maintain. +* Zed A. Shaw - for Mongrel, without which Unicorn would not be possible + +The original Mongrel contributors: + +* Luis Lavena +* Wilson Bilkovich +* Why the Lucky Stiff +* Dan Kubb +* MenTaLguY +* Filipe Lautert +* Rick Olson +* Wayne E. Seguin +* Kirk Haines +* Bradley Taylor +* Matt Pelletier +* Ry Dahl +* Nick Sieger +* Evan Weaver +* Marc-André Cournoyer diff --git a/DESIGN b/DESIGN index cc359ca..288502b 100644 --- a/DESIGN +++ b/DESIGN @@ -32,7 +32,8 @@ Rack application itself is called only within the worker process (but can be loaded within the master). A copy-on-write friendly garbage collector like Ruby Enterprise Edition can be used to minimize memory - usage along with the "preload_app true" directive. + usage along with the "preload_app true" directive (see + Unicorn::Configurator). * The number of worker processes should be scaled to the number of CPUs, memory or even spindles you have. If you have an existing diff --git a/README b/README index 1bd0305..bfd81ee 100644 --- a/README +++ b/README @@ -35,7 +35,7 @@ proxy we know of that meets this requirement. == License Unicorn is copyright 2009 Eric Wong and contributors. -It is based on Mongrel: +It is based on Mongrel and carries the same 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 @@ -46,19 +46,43 @@ details. 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. +You may download the tarball from the Mongrel project page on Rubyforge +and run setup.rb after unpacking it: -You can get the source via git via the following locations: + http://rubyforge.org/frs/?group_id=1306 - git://git.bogomips.org/unicorn.git +You may also install it via Rubygems on Rubyforge: + + gem install unicorn +You can get the latest source via git from the following locations +(these versions may not be stable): + + git://git.bogomips.org/unicorn.git http://git.bogomips.org/unicorn.git + git://repo.or.cz/unicorn.git (mirror) + http://repo.or.cz/r/unicorn.git (mirror) + +If you have web browser software for the World Wide Web +(on the Information Superhighway), you may browse the code from +your web browser and download the latest snapshot tarballs here: + +* http://git.bogomips.org/cgit/unicorn.git +* http://repo.or.cz/w/unicorn.git (gitweb mirror) == Usage +=== non-Rails Rack applications + Unicorn will look for the config.ru file used by rackup in APP_ROOT. -Optionally, it can use a config file specified by the --config-file/-c -command-line switch. +Optionally, it can use a config file for unicorn-specific options +specified by the --config-file/-c command-line switch. See +Unicorn::Configurator for the syntax of the unicorn-specific +config options. + +In APP_ROOT, just run: + + unicorn Unicorn should be capable of running most Rack applications. Since this is a preforking webserver, you do not have to worry about thread-safety @@ -66,17 +90,38 @@ of your application or libraries. However, your Rack application may use threads internally (and should even be able to continue running threads after the request is complete). +=== Rack-enabled versions of Rails (v2.3.2+) + +In RAILS_ROOT, run: + + unicorn_rails + +Most command-line options for other Rack applications (above) are also +supported. The unicorn_rails launcher attempts to combine the best +features of the Rails-bundled "script/server" with the "rackup"-like +functionality of the `unicorn' launcher. + +== Disclaimer + +There are no known production instances of unicorn deployed +anywhere in the world. The original author of unicorn only has +one, internal, low-traffic Sinatra application deployed with it. +Maybe you'll be the first guinea pig to test it in production. +Of course there is NO WARRANTY whatsoever if anything goes wrong, +but let us know and we'll try our best to fix it. + == Known Issues - * WONTFIX: code reloading with Sinatra 0.3.2 (and likely older - versions) apps is broken. Since this is no longer an issue with - Sinatra 0.9.x apps and only affected non-production instances, this - will not be fixed on our end. Also remember we're capable of - replacing the running binary without dropping any connections - regardless of framework :) +* WONTFIX: code reloading with Sinatra 0.3.2 (and likely older + versions) apps is broken. The workaround is to force production + mode to disable code reloading in your Sinatra application: + set :env, :production + Since this is no longer an issue with Sinatra 0.9.x apps and only + affected non-production instances, this will not be fixed on our end. + Also remember we're capable of replacing the running binary without + dropping any connections regardless of framework :) == Contact -Newsgroup and mailing list coming, or it'll be a part of the Mongrel project... - +Newsgroup and mailing list maybe coming... Email Eric Wong at normalperson@yhbt.net for now. -- cgit v1.2.3-24-ge0c7