rockdog-passenger 0.0.1

data/doc/Security of user switching support.txt

@@ -0,0 +1,197 @@
+Security of user switching support in Passenger
+===============================================
+
+Problem description
+-------------------
+TIP: It is strongly recommended that you first read our
+link:Architectural%20overview.html[Architectural Overview].
+
+A straightforward implementation of Passenger will spawn Rails applications in
+the same user context as Apache itself. On server machines which host multiple
+websites for multiple users, this may not be desired. All Rails applications
+spawned by Passenger will be able to read and write to all directories that the
+web server can. So for example, Joe's Rails applications could read Jane's
+Rails application's 'database.yml' or delete her application files. This is
+also a problem that typically plagues PHP web hosts.
+
+There are multiple ways to solve this problem. The goal of this document is to
+inform the reader about the solutions have we have analyzed, so that
+Passenger's security may be peer reviewed.
+
+
+Analysis of possible solutions
+------------------------------
+It seems that the only way to solve this problem on Unix, is to run each Rails
+application server as its owner's user and group. Passenger can make use of
+one of the following methods to implement this:
+
+ 1. Apache (and thus Passenger) must already be running as root.
+ 2. Using Apache's suEXEC.
+ 3. A setuid root wrapper application must exist, to allow non-root processes
+    to obtain root privileges (or at least, the privilege to switch user).
+ 4. For each user $X that Passenger will need to switch to, there must exist
+    a setuid $X wrapper application.
+ 5. Using 'su'.
+ 6. Using 'sudo'.
+
+Let us take a look at each method in detail.
+
+[[apache_root]]
+Apache must already be running as root
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+First, let us take a look at the typical Apache setup, in which Apache is bound
+to port 80, and uses the prefork MPM. Binding to any port lower than 1024
+requires root privileges, so Apache is typically run as root. This poses an
+unacceptable security risk, so Apache's prefork MPM will, upon receiving an
+HTTP request, spawn a child process with the privileges of a normal user,
+typically 'www-data' or 'nobody'.
+See http://httpd.apache.org/docs/2.2/mod/prefork.html[the documentation for the
+prefork MPM] - in particular the ``User'' and ``Group'' directives - for details.
+The process which is responsible for spawning child processes (also called the
+control process) is run as root. This is also true for
+http://httpd.apache.org/docs/2.2/mod/worker.html[the worker MPM].
+
+Since Passenger has access to the control process, in the typical Apache setup,
+Passenger can already launch Rails applications as a different user. But now we
+have to ask this question:
+
+=================================
+If Apache is not running as root, are there still any Passenger users who
+want to run Rails applications as different users?
+=================================
+
+If the answer is yes, then we cannot use this method.
+
+The advantage of this method is that setting up Apache to run as root is
+incredibly easy, and requires no new framework to be written. However, testing
+this method in automated unit tests will require running the unit test suit as
+root.
+
+Using Apache's suEXEC
+~~~~~~~~~~~~~~~~~~~~~
+Apache's http://httpd.apache.org/docs/2.0/suexec.html[suEXEC] allows one to
+run CGI processes as different users. But it seems that suEXEC can only be
+used for CGI, and is not a general-purpose mechanism. The
+http://alain.knaff.lu/howto/PhpSuexec/[PHP-suEXEC] software allows one to run
+PHP applications via suEXEC, but it requires patching suEXEC. If Passenger is
+to use suEXEC, then it is likely that we'll have to patch suEXEC. The suEXEC
+website strongly discourages patching.
+
+Using a setuid root wrapper application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If we use this method, we must be extremely careful. It must not be possible
+for arbitrary processes to gain root privileges. We want Passenger, and only
+Passenger, to be able to gain root privileges.
+
+There are multiple ways to implement this security. The first one is to use
+a password file, which only Apache and the wrapper can read, through
+the use of proper file permissions. The password file must never be world
+readable or writable.
+
+It works as follows:
+
+1. Passenger runs the wrapper.
+2. Passenger passes the content of the password file to the wrapper, via
+   an anonymous pipe (or some other anonymous channel, that no other
+   processes can access).
+3. The wrapper checks whether the passed content is the same as what is in
+   the password file. If it is, then it is proven that whatever application
+   ran the wrapper has read access to the password file, and thus is authorized
+   to use the wrapper.
+
+An obvious problem that arises is: how does the wrapper locate its own password
+file? We obviously do not want to be able to specify the password filename as
+an argument to the wrapper: that would defeat the point of the password file.
+The solution is that the filename is to be hardcoded into the binary during
+compile time.
+
+Another way to implement security is to use a whitelist of users that are
+allowed to use the wrapper. The wrapper can then check whether the calling
+process's user is in the whitelist.
+
+Writing a wrapper is not too hard. Furthermore, unit tests do not have to be
+run as root, in contrast to the run-Apache-as-root method.
+
+[[setuid_root]]
+Using a setuid $X wrapper application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A setuid $X wrapper will work in a fashion similar to the setuid root wrapper,
+i.e. it will use a password file for authorization.
+
+Passenger does not spawn Rails applications itself, but does so via the spawn
+server. This spawn server is also responsible for preloading the Rails
+framework and the Rails application code, in order to speed up the spawning
+of Rails applications. See the design document of the spawn server for details.
+The spawn server never calls `exec()`: doing so will make preloading useless.
+If Passenger is to use a setuid $X wrapper, then it must start the spawn
+server via the wrapper. The spawn server itself cannot use the wrapper.
+
+However, doing so will make preloading less efficient. Passenger will be forced
+to run a spawn server for each user. The different spawn servers do not share
+memory with each other, so a lot of memory is wasted compared to the other
+methods.
+
+Implementing this will also take more work. One has to create a different
+wrapper for each user, and to install it.
+
+Using 'su'
+~~~~~~~~~~
+The standard Unix 'su' tool asks for the root password. It's a bad idea for
+Apache to know the root password, so using 'su' is not a viable alternative.
+
+Using 'sudo'
+~~~~~~~~~~~~
+It might be possible to use the 'sudo' utility. sudo can be configured in
+such a way that the user Apache runs as can use sudo without having to enter a
+password.
+
+However, Passenger uses an anonymous communication channel (an unnamed Unix
+socket) to communicate with the spawn server. sudo seems to close all file
+descriptors before executing an application, so Passenger will have to
+communicate with the spawn server via a non-anonymous channel, such as a named
+Unix socket. Because other processes can access this channel, it can introduce
+potential security problems. Note that passing information via program arguments
+is not secure: it is possible to view that information with tools like 'ps',
+or (on Linux) by reading the file `/proc/$PID/cmdline`.
+
+So it seems 'sudo' is not a viable alternative.
+
+Common security issues
+~~~~~~~~~~~~~~~~~~~~~~
+Whatever method Passenger will use, the following security principles must be
+honored:
+
+ - Rails applications must never be run as root.
+
+It might also be worthy to look into suEXEC's security model for inspiration.
+
+Also, the following questions remain:
+
+ - Is there a need for a user whitelist/blacklist? That is, is there a need for
+   the ability to restrict the set of users that Passenger can switch to?
+
+
+Chosen solution
+---------------
+Running Apache as root and writing a setuid root wrapper are the main
+contestants. The former is preferred, because it's easier to implement.
+
+We have had some conversations with people on the IRC channel #rubyonrails.
+Among those people, nobody has ever run Apache as non-root. Because of this
+we have chosen to implement the <<apache_root,Running Apache as root>>
+solution, until a significant number of users request us to implement the
+<<setuid_root,setuid root wrapper>> solution.
+
+Please read link:rdoc/index.html[the Ruby API documentation] -- in particular
+that of the 'ApplicationSpawner' class -- for implementation details. But to
+make a long story short: it will switch to the owner of the file
+'config/environment.rb'. User whitelisting/blacklisting is currently not
+implemented. We rely on the system administrator to set the correct owner
+on that file.
+
+We have also not implemented suEXEC's security model. suEXEC's model is quite
+paranoid, and although paranoia is good to a certain extend, it can be in the
+way of usability while proving little extra security. We are not entirely
+convinced that implementing suEXEC's full security model will provide
+significant benefits, but if you have good reasons to think otherwise, please
+feel free to discuss it with us.

data/doc/Users guide.txt

@@ -0,0 +1,2237 @@
+= Phusion Passenger users guide =
+
+image:images/phusion_banner.png[link="http://www.phusion.nl/"]
+
+Phusion Passenger is an Apache module, which makes deploying Ruby and Ruby on
+Rails applications on Apache a breeze. It follows the usual Ruby on Rails
+conventions, such as "Don't-Repeat-Yourself" and ease of setup, while at the
+same time providing enough flexibility.
+
+This users guide will teach you:
+
+- How to install Phusion Passenger.
+- How to configure Phusion Passenger.
+- How to deploy a Ruby on Rails application.
+- How to deploy a link:http://rack.rubyforge.org/[Rack]-based Ruby application.
+- How to solve common problems.
+
+This guide assumes that the reader is somewhat familiar with Apache and with
+using the commandline.
+
+
+== Supported operating systems ==
+
+Phusion Passenger works on any POSIX-compliant operating system. In other
+words: practically any operating system on earth, except Microsoft Windows.
+
+Phusion Passenger has been tested on:
+
+- Ubuntu Linux 6.06 (x86)
+- Ubuntu Linux 7.10 (x86)
+- Ubuntu Linux 8.04 (x86)
+- Debian Sarge (x86)
+- Debian Etch (x86)
+- Debian Lenny/Sid (x86)
+- CentOS 5 (x86)
+- Red Hat Enterprise Linux 5 (x86)
+- Gentoo, March 14 2008 (AMD64)
+- FreeBSD 6.1-RELEASE (x86)
+- MacOS X Tiger (x86)
+- MacOS X Leopard (x86)
+
+Other operating systems have not been tested, but Phusion Passenger will probably
+work fine on them. Please
+link:http://code.google.com/p/phusion-passenger/issues/list[report a bug]
+or
+link:http://groups.google.com/group/phusion-passenger[join our discussion list]
+if it doesn't.
+
+
+== Installing Phusion Passenger ==
+
+=== Generic installation instructions ===
+
+[[install_passenger]]
+==== Overview of download and installation methods ====
+
+There are two ways to install Phusion Passenger:
+
+1. By installing the Phusion Passenger gem, as instructed on the
+   link:http://www.modrails.com/install.html[``Install'' page on the Phusion
+   Passenger website].
+2. By downloading a native Linux package (e.g. Debian package) from the
+   Phusion Passenger website.
+3. By downloading the source tarball from the Phusion Passenger website
+   ('passenger-x.x.x.tar.gz').
+
+In our opinion, installing the gem or the native package is easiest.
+
+Phusion Passenger provides an easy-to-use installer for installing the Phusion
+Passenger Apache module ('mod_passenger').
+
+TIP: You might have to run the installation commands in the following sections
+as 'root'. If the installer fails because of permission errors, it will tell
+you.
+
+[[specifying_correct_apache_install]]
+==== Specifying the correct Apache installation ====
+
+NOTE: You can skip this section if you've installed Phusion Passenger via a
+native Linux package, because no compilation is necessary.
+
+If your system has multiple Apache installations (this is likely the case on
+MacOS X), then you will need to tell the Phusion Passenger installer which one
+to use. If you only have one Apache installation (the case on most Linux
+systems), then you can skip this section because Phusion Passenger will
+automatically detect it.
+
+Every Apache installation has its own `apxs` program. You will need to tell
+Phusion Passenger the location of this program, by specifying the `APXS2`
+environment variable. Suppose that you want to use the Apache installation in
+'/opt/apache2'. Then, assuming that the corresponding `apxs` program is located
+'/opt/apache2/bin/apxs', type:
+----------------------------------
+export APXS2=/opt/apache2/bin/apxs
+----------------------------------
+
+NOTE: On some systems, the `apxs` program might be called `apxs2`, and it might
+be located in the `sbin` folder instead of the `bin` folder.
+
+[[specifying_ruby_installation]]
+==== Specifying the correct Ruby installation ====
+
+NOTE: You can skip this section if you've installed Phusion Passenger via a
+native Linux package, because no compilation is necessary.
+
+If your system has multiple Ruby installations (this is likely the case on
+MacOS X), then you will need to tell the Phusion Passenger installer which one
+to use. If you only have one Ruby installation (the case on most Linux systems),
+then you can skip this section because Phusion Passenger will automatically detect it.
+
+To specify the Ruby installation, prepend your Ruby installation's `bin`
+directory to the `PATH` environment variable. For example, if you have the
+following Ruby installations:
+
+- /usr/bin/ruby
+- /opt/myruby/bin/ruby
+
+and you want to use the latter, then type:
+
+----------------------------------
+export PATH=/opt/myruby/bin:$PATH
+----------------------------------
+
+
+==== Installing via the gem ====
+
+Please install the gem and then run the Phusion Passenger installer, by typing the
+following commands:
+------------------------------------------------------
+gem install passenger-x.x.x.gem
+passenger-install-apache2-module
+------------------------------------------------------
+Please follow the instructions given by the installer.
+
+==== Installing via a native Linux package ====
+
+Please install the native Linux package, e.g.:
+------------------------------------------------------
+gdebi passenger_x.x.x-i386.deb
+------------------------------------------------------
+
+Next, you'll need to configure Apache. Run the "installer", as it will tell you
+the correct configuration options for Apache:
+------------------------------------------------------
+passenger-install-apache2-module
+------------------------------------------------------
+
+NOTE: The installer doesn't actually install anything because it will automatically
+detect that Phusion Passenger has already been installed. The only thing the
+installer will do in this case, is showing the correct Apache configurations.
+
+==== Installing via the source tarball ====
+
+Extract the tarball to whatever location you prefer. The Phusion Passenger files
+are to reside in that location permanently. For example, if you would like
+Phusion Passenger to reside in `/opt/passenger-x.x.x`:
+------------------------------------------------------
+cd /opt
+tar xzvf ~/YourDownloadsFolder/passenger-x.x.x.tar.gz
+------------------------------------------------------
+
+Next, run the included installer:
+------------------------------------------------------
+/opt/passenger-x.x.x/bin/passenger-install-apache2-module
+------------------------------------------------------
+Please follow the instructions given by the installer.
+
+IMPORTANT: Please do not remove the 'passenger-x.x.x' folder after
+installation. Furthermore, the 'passenger-x.x.x' folder must be accessible by Apache.
+
+
+=== Operating system-specific instructions and information ===
+
+==== MacOS X ====
+
+Ben Ruebenstein has written an excellent
+link:http://benr75.com/articles/2008/04/12/setup-mod_rails-phusion-mac-os-x-leopard[tutorial
+on installing Phusion Passenger on OS X].
+
+==== Ubuntu Linux ====
+
+Ben Hughes has written an link:http://www.railsgarden.com/2008/04/12/configurating-passenger-mod_rails-on-slicehost-with-ubuntu-710/[article on installing Phusion Passenger on Ubuntu].
+
+
+== Deploying a Ruby on Rails application ==
+
+Suppose you have a Ruby on Rails application in '/webapps/mycook', and you own
+the domain 'www.mycook.com'. You can either deploy your application to the
+virtual host's root (i.e. the application will be accessible from the root URL,
+'http://www.mycook.com/'), or in a sub URI (i.e. the application will be
+accessible from a sub URL, such as 'http://www.mycook.com/railsapplication').
+
+NOTE: The default `RAILS_ENV` environment in which deployed Rails applications
+are run, is ``production''. You can change this by changing the
+<<rails_env,'RailsEnv'>> configuration option.
+
+=== Deploying to a virtual host's root ===
+
+Add a virtual host entry to your Apache configuration file. The virtual host's
+document root must point to your Ruby on Rails application's 'public' folder.
+For example:
+-------------------------------------------
+<VirtualHost *:80>
+    ServerName www.mycook.com
+    DocumentRoot /webapps/mycook/public
+</VirtualHost>
+-------------------------------------------
+Then restart Apache. The application has now been deployed.
+
+[[deploying_rails_to_sub_uri]]
+=== Deploying to a sub URI ===
+
+Suppose that you already have a virtual host:
+
+-------------------------------------------
+<VirtualHost *:80>
+    ServerName www.phusion.nl
+    DocumentRoot /websites/phusion
+</VirtualHost>
+-------------------------------------------
+
+And you want your Ruby on Rails application to be accessible from the URL
+'http://www.phusion.nl/rails'.
+
+To do this, make a symlink from your Ruby on Rails application's 'public'
+folder to a directory in the document root. For example:
+-------------------------------------------
+ln -s /webapps/mycook/public /websites/phusion/rails
+-------------------------------------------
+
+Next, add a <<RailsBaseURI,RailsBaseURI>> option to the virtual host configuration:
+-------------------------------------------
+<VirtualHost *:80>
+    ServerName www.phusion.nl
+    DocumentRoot /websites/phusion
+    RailsBaseURI /rails                # This line has been added.
+</VirtualHost>
+-------------------------------------------
+Then restart Apache. The application has now been deployed.
+
+[TIP]
+======================================
+You can deploy multiple Rails applications under a virtual host, by specifying
+<<RailsBaseURI,RailsBaseURI>> multiple times. For example:
+---------------------------------
+<VirtualHost *:80>
+    ....
+    RailsBaseURI /app1
+    RailsBaseURI /app2
+    RailsBaseURI /app3
+</VirtualHost>
+---------------------------------
+======================================
+
+=== Redeploying (restarting the Ruby on Rails application) ===
+
+Deploying a new version of a Ruby on Rails application is as simple as
+re-uploading the application files, and restarting the application.
+
+There are two ways to restart the application:
+
+1. By restarting Apache.
+2. By creating or modifying the file 'tmp/restart.txt' in the Rails
+   application's root folder. Phusion Passenger will automatically
+   restart the application.
+
+For example, to restart our example MyCook application, we type this in the
+command line:
+-------------------------------------------
+touch /webapps/mycook/tmp/restart.txt
+-------------------------------------------
+
+=== Migrations ===
+
+Phusion Passenger is not related to Ruby on Rails migrations in any way. To
+run migrations on your deployment server, please login to your deployment
+server (e.g. with 'ssh') and type `rake db:migrate RAILS_ENV=production` in
+a shell console, just like one would normally run migrations.
+
+=== Capistrano integration ===
+
+See <<capistrano,Capistrano recipe>>.
+
+
+== Deploying a Rack-based Ruby application ==
+
+Phusion Passenger supports arbitrary Ruby web applications that follow the
+link:http://rack.rubyforge.org/[Rack] interface.
+
+Phusion Passenger assumes that Rack application directories have a certain layout.
+Suppose that you have a Rack application in '/webapps/rackapp'. Then that
+folder must contain at least three entries:
+
+- 'config.ru', a Rackup file for starting the Rack application. This file must contain
+  the complete logic for initializing the application.
+- 'public/', a folder containing public static web assets, like images and stylesheets.
+- 'tmp/', used for 'restart.txt' (our application restart mechanism). This will
+  be explained in a following subsection.
+
+So '/webapps/rackapp' must, at minimum, look like this:
+----------------------
+/webapps/rackapp
+  |
+  +-- config.ru
+  |
+  +-- public/
+  |
+  +-- tmp/
+----------------------
+
+Suppose you own the domain 'www.rackapp.com'. You can either deploy your application
+to the virtual host's root (i.e. the application will be accessible from the root URL,
+'http://www.rackapp.com/'), or in a sub URI (i.e. the application will be
+accessible from a sub URL, such as 'http://www.rackapp.com/rackapp').
+
+NOTE: The default `RACK_ENV` environment in which deployed Rack applications
+are run, is ``production''. You can change this by changing the
+<<rack_env,'RackEnv'>> configuration option.
+
+=== Tutorial/example: writing and deploying a Hello World Rack application ===
+
+First we create a Phusion Passenger-compliant Rack directory structure:
+
+-------------------------------------------
+$ mkdir /webapps/rack_example
+$ mkdir /webapps/rack_example/public
+$ mkdir /webapps/rack_example/tmp
+-------------------------------------------
+
+Next, we write a minimal "hello world" Rack application:
+
+-------------------------------------------
+$ cd /webapps/rack_example
+$ some_awesome_editor config.ru
+...type in some source code...
+$ cat config.ru
+app = proc do |env|
+    return [200, { "Content-Type" => "text/html" }, "hello <b>world</b>"]
+end
+run app
+-------------------------------------------
+
+Finally, we deploy it by adding the following configuration options to
+the Apache configuration file:
+
+-------------------------------------------
+<VirtualHost *:80>
+    ServerName www.rackexample.com
+    DocumentRoot /webapps/rack_example/public
+</VirtualHost>
+-------------------------------------------
+
+And we're done! After an Apache restart, the above Rack application will be available
+under the URL 'http://www.rackexample.com/'.
+
+=== Deploying to a virtual host's root ===
+
+Add a virtual host entry to your Apache configuration file. The virtual host's
+document root must point to your Rack application's 'public' folder.
+For example:
+-------------------------------------------
+<VirtualHost *:80>
+    ServerName www.rackapp.com
+    DocumentRoot /webapps/rackapp/public
+</VirtualHost>
+-------------------------------------------
+Then restart Apache. The application has now been deployed.
+
+[[deploying_rack_to_sub_uri]]
+=== Deploying to a sub URI ===
+
+Suppose that you already have a virtual host:
+
+-------------------------------------------
+<VirtualHost *:80>
+    ServerName www.phusion.nl
+    DocumentRoot /websites/phusion
+</VirtualHost>
+-------------------------------------------
+
+And you want your Rack application to be accessible from the URL
+'http://www.phusion.nl/rack'.
+
+To do this, make a symlink from your Rack application's 'public'
+folder to a directory in the document root. For example:
+-------------------------------------------
+ln -s /webapps/rackapp/public /websites/phusion/rack
+-------------------------------------------
+
+Next, add a <<RackBaseURI,RackBaseURI>> option to the virtual host configuration:
+-------------------------------------------
+<VirtualHost *:80>
+    ServerName www.phusion.nl
+    DocumentRoot /websites/phusion
+    RackBaseURI /rack                # This line has been added.
+</VirtualHost>
+-------------------------------------------
+Then restart Apache. The application has now been deployed.
+
+[TIP]
+======================================
+You can deploy multiple Rack applications under a virtual host, by specifying
+<<RackBaseURI,RackBaseURI>> multiple times. For example:
+---------------------------------
+<VirtualHost *:80>
+    ....
+    RackBaseURI /app1
+    RackBaseURI /app2
+    RackBaseURI /app3
+</VirtualHost>
+---------------------------------
+======================================
+
+=== Redeploying (restarting the Rack application) ===
+
+Deploying a new version of a Rack application is as simple as
+re-uploading the application files, and restarting the application.
+
+There are two ways to restart the application:
+
+1. By restarting Apache.
+2. By creating or modifying the file 'tmp/restart.txt' in the Rack
+   application's root folder. Phusion Passenger will automatically restart the
+   application.
+
+For example, to restart our example application, we type this in the
+command line:
+-------------------------------------------
+touch /webapps/rackapp/tmp/restart.txt
+-------------------------------------------
+
+=== Rackup specifications for various web frameworks ===
+
+This subsection shows example 'config.ru' files for various web frameworks.
+
+==== Camping ====
+------------------------------------------------------
+require 'rubygems'
+require 'rack'
+require 'camping'
+
+##### Begin Camping application
+Camping.goes :Blog
+
+...your application code here...
+##### End Camping application
+
+run Rack::Adapter::Camping.new(Blog)
+------------------------------------------------------
+
+For Camping versions 2.0 and up, using `run Blog` as the final line will do.
+
+==== Halcyon ====
+------------------------------------------------------
+require 'rubygems'
+require 'halcyon'
+$LOAD_PATH.unshift(Halcyon.root / 'lib')
+Halcyon::Runner.load_config Halcyon.root/'config'/'config.yml'
+run Halcyon::Runner.new
+------------------------------------------------------
+
+==== Mack ====
+------------------------------------------------------
+ENV["MACK_ENV"] = ENV["RACK_ENV"]
+load("Rakefile")
+require 'rubygems'
+require 'mack'
+run Mack::Utils::Server.build_app
+------------------------------------------------------
+
+==== Merb ====
+------------------------------------------------------
+require 'rubygems'
+require 'merb-core'
+
+Merb::Config.setup(
+  :merb_root   => File.expand_path(File.dirname(__FILE__)),
+  :environment => ENV['RACK_ENV']
+)
+Merb.environment = Merb::Config[:environment]
+Merb.root = Merb::Config[:merb_root]
+Merb::BootLoader.run
+
+run Merb::Rack::Application.new
+------------------------------------------------------
+
+==== Ramaze ====
+------------------------------------------------------
+require "start"
+Ramaze.trait[:essentials].delete Ramaze::Adapter
+Ramaze.start :force => true
+run Ramaze::Adapter::Base
+------------------------------------------------------
+
+==== Sinatra ====
+------------------------------------------------------
+require 'rubygems'
+require 'sinatra'
+
+root_dir = File.dirname(__FILE__)
+
+Sinatra::Application.default_options.merge!(
+  :views    => File.join(root_dir, 'views'),
+  :app_file => File.join(root_dir, 'app.rb'),
+  :run => false,
+  :env => ENV['RACK_ENV'].to_sym
+)
+
+run Sinatra.application
+------------------------------------------------------
+
+
+== Configuring Phusion Passenger ==
+
+After installation, Phusion Passenger does not need any further configurations.
+Nevertheless, the system administrator may be interested in changing
+Phusion Passenger's behavior. Phusion Passenger's Apache module supports the
+following configuration options:
+
+=== PassengerRoot <directory> ===
+The location to the Phusion Passenger root directory. This configuration option
+is essential to Phusion Passenger. The correct value is given by the installer,
+and should usually not be changed manually.
+
+This required option may only occur once, in the global server configuration.
+
+=== PassengerLogLevel <integer> ===
+This option allows one to specify how much information Phusion Passenger should
+write to the Apache error log file. A higher log level value means that more
+information will be logged.
+
+Possible values are:
+
+- '0': Show only errors and warnings.
+- '1': Show the most important debugging information. This might be useful for
+       system administrators who are trying to figure out the cause of a
+       problem.
+- '2': Show more debugging information. This is typically only useful for developers.
+- '3': Show even more debugging information.
+
+This option may only occur once, in the global server configuration.
+The default is '0'.
+
+[[PassengerRuby]]
+=== PassengerRuby <filename> ===
+This option allows one to specify the Ruby interpreter to use.
+
+This option may only occur once, in the global server configuration.
+The default is 'ruby'.
+
+[[PassengerAppRoot]]
+=== PassengerAppRoot <path/to/root> ===
+By default, Phusion Passenger assumes that the application's root directory
+is the parent directory of the 'public' directory. This option allows one to
+specify the application's root independently from the DocumentRoot, which
+is useful if the 'public' directory lives in a non-standard place.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Options` is on.
+
+In each place, it may be specified at most once.
+
+Example:
+
+-----------------------------
+<VirtualHost test.host>
+    DocumentRoot /var/rails/zena/sites/example.com/public
+    PassengerAppRoot /var/rails/zena   # <-- normally Phusion Passenger would
+                                       #     have assumed that the application
+                                       #     root is "/var/rails/zena/sites/example.com"
+</VirtualHost>
+-----------------------------
+
+[[PassengerUseGlobalQueue]]
+=== PassengerUseGlobalQueue <on|off> ===
+Turns the use of global queuing on or off.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+
+In each place, it may be specified at most once. The default value is 'off'.
+
+'This feature is sponsored by http://www.37signals.com/[37signals].'
+
+.What does this option do?
+
+Recall that Phusion Passenger spawns multiple backend processes (e.g. multiple
+Ruby on Rails processes), each which processes HTTP requests serially. One of
+Phusion Passenger's jobs is to forward HTTP requests to a suitable backend
+process. A backend process may take an arbitrary amount of time to process a
+specific HTTP request. If the websites are (temporarily) under high load, and
+the backend processes cannot process the requests fast enough, then some
+requests may have to be queued.
+
+If global queuing is turned off, then Phusion Passenger will use 'fair load
+balancing'. This means that each backend process will have its own private
+queue. Phusion Passenger will forward an HTTP request to the backend process
+that has the least amount of requests in its queue.
+
+If global queuing is turned on, then Phusion Passenger will use a global queue
+that's shared between all backend processes. If an HTTP request comes in, and
+all the backend processes are still busy, then Phusion Passenger will wait until
+at least one backend process is done, and will then forward the request to that
+process.
+
+.When to turn on global queuing?
+
+You should turn on global queuing if one of your web applications may have
+long-running requests.
+
+For example suppose that:
+
+- global queuing is turned off.
+- we're currently in a state where all backend processes have 3 requests in
+  their queue, except for a single backend process, which has 1 request in its
+  queue.
+
+The situation looks like this:
+
+--------------------------------------------------
+Backend process A:  [*     ]  (1 request in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+Each process is currently serving short-running requests.
+
+Phusion Passenger will forward the next request to backend process A. A will
+now have 2 items in its queue. We'll mark this new request with an X:
+
+--------------------------------------------------
+Backend process A:  [*X    ]  (2 request in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+Assuming that B, C and D still aren't done with their current request, the next
+HTTP request - let's call this Y - will be forwarded to backend process A as
+well, because it has the least number of items in its queue:
+
+--------------------------------------------------
+Backend process A:  [*XY   ]  (3 requests in queue)
+Backend process B:  [***   ]  (3 requests in queue)
+Backend process C:  [***   ]  (3 requests in queue)
+Backend process D:  [***   ]  (3 requests in queue)
+--------------------------------------------------
+
+But if request X happens to be a long-running request that needs 60 seconds to
+complete, then we'll have a problem. Y won't be processed for at least 60
+seconds. It would have been a better idea if Y was forward to processes B, C or
+D instead, because they only have short-living requests in their queues.
+
+This problem will be avoided entirely if you turn global queuing on. With global
+queuing, all backend processes will share the same queue. The first backend
+process that becomes available will take from the queue, and so this
+``queuing-behind-long-running-request'' problem will never occur.
+
+Turning global queuing off will yield a minor performance improvement (about 5%,
+depending on how fast/slow your web application is), which is why it's off by
+default.
+
+
+[[PassengerUserSwitching]]
+=== PassengerUserSwitching <on|off> ===
+Whether to enable <<user_switching,user switching support>>.
+
+This option may only occur once, in the global server configuration.
+The default value is 'on'.
+
+[[PassengerDefaultUser]]
+=== PassengerDefaultUser <username> ===
+Passenger enables <<user_switching,user switching support>> by default.
+This configuration option allows one to specify which user Rails/Rack
+applications must run as, if user switching fails or is disabled.
+
+This option may only occur once, in the global server configuration.
+The default value is 'nobody'.
+
+[[PassengerHighPerformance]]
+=== PassengerHighPerformance <on|off> ===
+By default, Phusion Passenger is compatible with mod_rewrite and most other
+Apache modules. However, a lot of effort is required in order to be compatible.
+If you turn 'PassengerHighPerformance' to 'on', then Phusion Passenger will be
+a little faster, in return for reduced compatibility with other Apache modules.
+
+In places where 'PassengerHighPerformance' is turned on, mod_rewrite rules will
+likely not work. mod_autoindex (the module which displays a directory index)
+will also not work. Other Apache modules may or may not work, depending on what
+they exactly do. We recommend you to find out how other modules behave in high
+performance mode via testing.
+
+This option is *not* an all-or-nothing global option: you can enable high
+performance mode for certain virtual hosts or certain URLs only.
+The 'PassengerHighPerformance' option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess'.
+
+In each place, it may be specified at most once. The default value is 'off',
+so high performance mode is disabled by default, and you have to explicitly
+enable it.
+
+.When to enable high performance mode?
+
+If you do not use mod_rewrite or other Apache modules then it might make
+sense to enable high performance mode.
+
+It's likely that some of your applications depend on mod_rewrite or other
+Apache modules, while some do not. In that case you can enable high performance
+for only those applications that don't use other Apache modules. For example:
+
+------------------------------------
+<VirtualHost *:80>
+    ServerName www.foo.com
+    DocumentRoot /apps/foo/public
+    .... mod_rewrite rules or options for other Apache modules here ...
+</VirtualHost>
+
+<VirtualHost *:80>
+    ServerName www.bar.com
+    DocumentRoot /apps/bar/public
+    PassengerHighPerformance on
+</VirtualHost>
+------------------------------------
+
+In the above example, high performance mode is only enabled for www.bar.com.
+It is disabled for everything else.
+
+If your application generally depends on mod_rewrite or other Apache modules,
+but a certain URL that's accessed often doesn't depend on those other modules,
+then you can enable high performance mode for a certain URL only. For example:
+
+------------------------------------
+<VirtualHost *:80>
+    ServerName www.foo.com
+    DocumentRoot /apps/foo/public
+    .... mod_rewrite rules or options for other Apache modules here ...
+    
+    <Location /chatroom/ajax_update_poll>
+        PassengerHighPerformance on
+    </Location>
+</VirtualHost>
+------------------------------------
+
+This enables high performance mode for
+http://www.foo.com/chatroom/ajax_update_poll only.
+
+=== PassengerEnabled <on|off> ===
+You can set this option to 'off' to completely disable Phusion Passenger for
+a certain location. This is useful if, for example, you want to integrate a PHP
+application into the same virtual host as a Rails application.
+
+Suppose that you have a Rails application in '/apps/foo'. Suppose that you've
+dropped Wordpress -- a blogging application written in PHP -- in
+'/apps/foo/public/wordpress'. You can then configure Phusion Passenger as
+follows:
+
+------------------------------------
+<VirtualHost *:80>
+    ServerName www.foo.com
+    DocumentRoot /apps/foo/public
+    <Location /wordpress>
+        PassengerEnabled off
+    </Location>
+</VirtualHost>
+------------------------------------
+
+This way, Phusion Passenger will not interfere with Wordpress.
+
+'PassengerEnabled' may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess'.
+
+In each place, it may be specified at most once. The default value is 'on'.
+
+=== PassengerTempDir <directory> ===
+Specifies the directory that Phusion Passenger should use for storing temporary
+files. This includes things such as Unix socket files, buffered file uploads,
+etc.
+
+This option may be specified once, in the global server configuration. The
+default temp directory that Phusion Passenger uses is '/tmp'.
+
+This option is especially useful if Apache is not allowed to write to /tmp
+(which is the case on some systems with strict SELinux policies) or if the
+partition that /tmp lives on doesn't have enough disk space.
+
+.Command line tools
+Some Phusion Passenger command line administration tools, such as
+`passenger-status`, must know what Phusion Passenger's temp directory is
+in order to function properly. You can pass the directory through the
+`PASSENGER_TMPDIR` environment variable, or the `TMPDIR` environment variable
+(the former will be used if both are specified).
+
+For example, if you set 'PassengerTempDir' to '/my_temp_dir', then invoke
+`passenger-status` after you've set the `PASSENGER_TMPDIR` or `TMPDIR`
+environment variable, like this:
+
+----------------------------------------------------------
+export PASSENGER_TMPDIR=/my_temp-dir
+sudo -E passenger-status
+# The -E option tells 'sudo' to preserve environment variables.
+----------------------------------------------------------
+
+=== PassengerRestartDir <directory> ===
+As described in the deployment chapters of this document, Phusion Passenger
+checks the file 'tmp/restart.txt' in the applications'
+<<application_root,root directory>> for restarting applications. Sometimes it
+may be desirable for Phusion Passenger to look in a different directory instead,
+for example for security reasons (see below). This option allows you to
+customize the directory in which 'restart.txt' is searched for.
+
+You may specify 'PassengerRestartDir' in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverrides Options` is enabled.
+
+In each place, it may be specified at most once.
+
+You can either set it to an absolute directory, or to a directory relative to
+the <<application_root,application root>>. Examples:
+
+-----------------------------------
+<VirtualHost *:80>
+    ServerName www.foo.com
+    # Phusion Passenger will check for /apps/foo/public/tmp/restart.txt
+    DocumentRoot /apps/foo/public
+</VirtualHost>
+
+<VirtualHost *:80>
+    ServerName www.bar.com
+    DocumentRoot /apps/bar/public
+    # An absolute filename is given; Phusion Passenger will
+    # check for /restart_files/bar/restart.txt
+    PassengerRestartDir /restart_files/bar
+</VirtualHost>
+
+<VirtualHost *:80>
+    ServerName www.baz.com
+    DocumentRoot /apps/baz/public
+    # A relative filename is given; Phusion Passenger will
+    # check for /apps/baz/restart_files/restart.txt
+    #
+    # Note that this directory is relative to the APPLICATION ROOT, *not*
+    # the value of DocumentRoot!
+    PassengerRestartDir restart_files
+</VirtualHost>
+-----------------------------------
+
+.What are the security reasons for wanting to customize PassengerRestartDir?
+Touching restart.txt will cause Phusion Passenger to restart the application.
+So anybody who can touch restart.txt can effectively cause a Denial-of-Service
+attack by touching restart.txt over and over. If your web server or one of your
+web applications has the permission to touch restart.txt, and one of them has a
+security flaw which allows an attacker to touch restart.txt, then that will
+allow the attacker to cause a Denial-of-Service.
+
+You can prevent this from happening by pointing PassengerRestartDir to a
+directory that's readable by Apache, but only writable by administrators.
+
+
+=== Resource control and optimization options ===
+
+==== PassengerMaxPoolSize <integer> ====
+The maximum number of Ruby on Rails or Rack application instances that may
+be simultaneously active. A larger number results in higher memory usage,
+but improved ability to handle concurrent HTTP clients.
+
+The optimal value depends on your system's hardware and the server's average
+load. You should experiment with different values. But generally speaking,
+the value should be at least equal to the number of CPUs (or CPU cores) that
+you have. If your system has 2 GB of RAM, then we recommend a value of '30'.
+If your system is a Virtual Private Server (VPS) and has about 256 MB RAM, and
+is also running other services such as MySQL, then we recommend a value of '2'.
+
+If you find that your server is unable to handle the load on your Rails/Rack websites
+(i.e. running out of memory) then you should lower this value. (Though if your
+sites are really that popular, then you should strongly consider upgrading your
+hardware or getting more servers.)
+
+This option may only occur once, in the global server configuration.
+The default value is '6'.
+
+TIP: We strongly recommend you to <<reducing_memory_usage,use Ruby Enterprise
+Edition>>. This allows you to reduce the memory usage of your Ruby on Rails applications
+by about 33%. And it's not hard to install.
+
+==== PassengerMaxInstancesPerApp <integer> ====
+The maximum number of application instances that may be simultaneously active
+for a single application. This helps to make sure that a single application
+will not occupy all available slots in the application pool.
+
+This value must be less than <<PassengerMaxPoolSize,PassengerMaxPoolSize>>. A value of 0
+means that there is no limit placed on the number of instances a single application
+may use, i.e. only the global limit of <<PassengerMaxPoolSize,PassengerMaxPoolSize>>
+will be enforced.
+
+This option may only occur once, in the global server configuration.
+The default value is '0'.
+
+[[PassengerPoolIdleTime]]
+==== PassengerPoolIdleTime <integer> ====
+The maximum number of seconds that an application instance may be idle. That is,
+if an application instance hasn't received any traffic after the given number of
+seconds, then it will be shutdown in order to conserve memory.
+
+Decreasing this value means that applications will have to be spawned
+more often. Since spawning is a relatively slow operation, some visitors may
+notice a small delay when they visit your Rails/Rack website. However, it will also
+free up resources used by applications more quickly.
+
+The optimal value depends on the average time that a visitor spends on a single
+Rails/Rack web page. We recommend a value of `2 * x`, where `x` is the average
+number of seconds that a visitor spends on a single Rails/Rack web page. But your
+mileage may vary.
+
+When this value is set to '0', application instances will not be shutdown unless 
+it's really necessary, i.e. when Phusion Passenger is out of worker processes
+for a given application and one of the inactive application instances needs to
+make place for another application instance. Setting the value to 0 is
+recommended if you're on a non-shared host that's only running a few
+applications, each which must be available at all times.
+
+This option may only occur once, in the global server configuration.
+The default value is '300'.
+
+[[PassengerMaxRequests]]
+==== PassengerMaxRequests <integer> ====
+The maximum number of requests an application instance will process. After
+serving that many requests, the application instance will be shut down and
+Phusion Passenger will restart it. A value of 0 means that there is no maximum:
+an application instance will thus be shut down when its idle timeout has been
+reached.
+
+This option is useful if your application is leaking memory. By shutting
+it down after a certain number of requests, all of its memory is guaranteed
+to be freed by the operating system.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Limits` is on.
+
+In each place, it may be specified at most once. The default value is '0'.
+
+[CAUTION]
+=====================================================
+The <<PassengerMaxRequests,PassengerMaxRequests>> directive should be considered
+as a workaround for misbehaving applications. It is advised that you fix the
+problem in your application rather than relying on these directives as a
+measure to avoid memory leaks.
+=====================================================
+
+==== PassengerStatThrottleRate <integer> ====
+By default, Phusion Passenger performs several filesystem checks (or, in
+programmers jargon, 'stat() calls') each time a request is processed:
+
+- It checks whether 'config/environment.rb', 'config.ru' or 'passenger_wsgi.py'
+  is present, in order to autodetect Rails, Rack and WSGI applications.
+- It checks whether 'restart.txt' has changed or whether 'always_restart.txt'
+  exists, in order to determine whether the application should be restarted.
+
+On some systems where disk I/O is expensive, e.g. systems where the harddisk is
+already being heavily loaded, or systems where applications are stored on NFS
+shares, these filesystem checks can incur a lot of overhead.
+
+You can decrease or almost entirely eliminate this overhead by setting
+'PassengerStatThrottleRate'. Setting this option to a value of 'x' means that
+the above list of filesystem checks will be performed at most once every 'x'
+seconds. Setting it to a value of '0' means that no throttling will take place,
+or in other words, that the above list of filesystem checks will be performed on
+every request.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Limits` is on.
+
+In each place, it may be specified at most once. The default value is '0'.
+
+
+=== Ruby on Rails-specific options ===
+
+==== RailsAutoDetect <on|off> ====
+Whether Phusion Passenger should automatically detect whether a virtual host's
+document root is a Ruby on Rails application. The default is 'on'.
+
+This option may occur in the global server configuration or in a virtual host
+configuration block.
+
+For example, consider the following configuration:
+
+-----------------------------
+RailsAutoDetect off
+<VirtualHost *:80>
+    ServerName www.mycook.com
+    DocumentRoot /webapps/mycook/public
+</VirtualHost>
+-----------------------------
+
+If one goes to 'http://www.mycook.com/', the visitor will see the contents of
+the '/webapps/mycook/public' folder, instead of the output of the Ruby on Rails
+application.
+
+It is possible to explicitly specify that the host is a Ruby on Rails
+application by using the <<RailsBaseURI,RailsBaseURI>> configuration option:
+
+-----------------------------
+RailsAutoDetect off
+<VirtualHost *:80>
+    ServerName www.mycook.com
+    DocumentRoot /webapps/mycook/public
+    RailsBaseURI /           # This line has been added.
+</VirtualHost>
+-----------------------------
+
+[[RailsBaseURI]]
+==== RailsBaseURI <uri> ====
+Used to specify that the given URI is a Rails application. See
+<<deploying_rails_to_sub_uri,Deploying Rails to a sub URI>> for an example.
+
+It is allowed to specify this option multiple times. Do this to deploy multiple
+Rails applications in different sub-URIs under the same virtual host.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Options` is on.
+
+[[rails_env]]
+==== RailsEnv <string> ====
+This option allows one to specify the default `RAILS_ENV` value.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Options` is on.
+
+In each place, it may be specified at most once. The default value is 'production'.
+
+[[RailsSpawnMethod]]
+==== RailsSpawnMethod <string> ====
+[TIP]
+."What spawn method should I use?"
+=========================================================
+This subsection attempts to describe spawn methods, but it's okay if you don't (want to)
+understand it, as it's mostly a technical detail. You can basically follow this rule of thumb:
+
+************************************************
+If your application works on Mongrel, but not on Phusion Passenger, then set
+`RailsSpawnMethod` to 'conservative'. Otherwise, leave it at 'smart-lv2' (the default).
+************************************************
+
+However, we do recommend you to try to understand it. The 'smart' and 'smart-lv2' spawn
+methods bring many benefits.
+=========================================================
+
+Internally, Phusion Passenger spawns multiple Ruby on Rails processes in order to handle
+requests. But there are multiple ways with which processes can be spawned, each having
+its own set of pros and cons. Supported spawn methods are:
+
+'smart'::
+When this spawn method is used, Phusion Passenger will attempt to cache Ruby on Rails
+framework code and application code for a limited period of time. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what smart spawning exactly does.
++
+*Pros:*
+This can significantly decrease spawn time (by as much as 90%). And, when Ruby Enterprise
+Edition is used, <<reducing_memory_usage,memory usage can be reduced by 33% on average>>.
++
+*Cons:*
+Some Ruby on Rails applications and libraries are not compatible with smart spawning.
+If that's the case for your application, then you should use 'conservative' as
+spawning method.
+
+'smart-lv2'::
+This spawning method is similar to 'smart' but it skips the framework spawner
+and uses the application spawner directly. This means the framework code is not
+cached between multiple applications, although it is still cached within
+instances of the same application. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what smart-lv2 spawning exactly does.
++
+*Pros:* It is compatible with a larger number of applications when compared to
+the 'smart' method, and still performs some caching.
++
+*Cons:* It is slower than smart spawning if you have many applications which
+use the same framework version. It is therefore advised that shared hosts use the
+'smart' method instead.
+
+'conservative'::
+This spawning method is similar to the one used in Mongrel Cluster. It does not
+perform any code caching at all. Please read
+<<spawning_methods_explained,Spawning methods explained>> for a more detailed
+explanation of what conservative spawning exactly does.
++
+*Pros:*
+Conservative spawning is guaranteed to be compatible with all Rails applications
+and libraries.
++
+*Cons:*
+Much slower than smart spawning. Every spawn action will be equally slow, though no slower than
+the startup time of a single server in Mongrel Cluster. Conservative spawning will also
+render <<reducing_memory_usage,Ruby Enterprise Edition's memory reduction technology>> useless.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+
+In each place, it may be specified at most once. The default value is 'smart-lv2'.
+
+=== Rack-specific options ===
+
+==== RackAutoDetect <on|off> ====
+Whether Phusion Passenger should automatically detect whether a virtual host's
+document root is a Rack application. The default is 'on'.
+
+This option may occur in the global server configuration or in a virtual host
+configuration block.
+
+For example, consider the following configuration:
+
+-----------------------------
+RackAutoDetect off
+<VirtualHost *:80>
+    ServerName www.rackapp.com
+    DocumentRoot /webapps/my_rack_app/public
+</VirtualHost>
+-----------------------------
+
+If one goes to 'http://www.rackapp.com/', the visitor will see the contents of
+the '/webapps/my_rack_app/public' folder, instead of the output of the Rack
+application.
+
+It is possible to explicitly specify that the host is a Rack
+application by using the <<RackBaseURI,RackBaseURI>> configuration option:
+
+-----------------------------
+RackAutoDetect off
+<VirtualHost *:80>
+    ServerName www.rackapp.com
+    DocumentRoot /webapps/my_rack_app/public
+    RackBaseURI /       # This line was added
+</VirtualHost>
+-----------------------------
+
+[[RackBaseURI]]
+==== RackBaseURI <uri> ====
+Used to specify that the given URI is a Rack application. See
+<<deploying_rack_to_sub_uri,Deploying Rack to a sub URI>> for an example.
+
+It is allowed to specify this option multiple times. Do this to deploy multiple
+Rack applications in different sub-URIs under the same virtual host.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Options` is on.
+
+[[rack_env]]
+==== RackEnv <string> ====
+The given value will be accessible in Rack applications in the `RACK_ENV`
+environment variable. This allows one to define the environment in which
+Rack applications are run, very similar to `RAILS_ENV`.
+
+This option may occur in the following places:
+
+ * In the global server configuration.
+ * In a virtual host configuration block.
+ * In a `<Directory>` or `<Location>` block.
+ * In '.htaccess', if `AllowOverride Options` is on.
+
+In each place, it may be specified at most once. The default value is 'production'.
+
+=== Deprecated options ===
+
+The following options have been deprecated, but are still supported for backwards
+compatibility reasons.
+
+==== RailsRuby ====
+Deprecated in favor of <<PassengerRuby,PassengerRuby>>.
+
+==== RailsUserSwitching ====
+Deprecated in favor of <<PassengerUserSwitching,PassengerUserSwitching>>.
+
+==== RailsDefaultUser ====
+Deprecated in favor of <<PassengerDefaultUser,PassengerDefaultUser>>.
+
+==== RailsAllowModRewrite ====
+This option doesn't do anything anymore in recent versions of Phusion Passenger.
+
+
+== Troubleshooting ==
+
+=== Operating system-specific problems ===
+
+==== MacOS X: The installer cannot locate MAMP's Apache ====
+
+.Symptoms
+*******************************************************************************
+The installer finds Apache 2 development headers at `/Applications/MAMP/Library/bin/apxs`.
+However, Apache cannot be found. The installer also outputs the following error:
+------------------------------------
+cannot open /Applications/MAMP/Library/build/config_vars.mk:
+No such file or directory at /Applications/MAMP/Library/bin/apxs line 218.
+------------------------------------
+*******************************************************************************
+
+Your MAMP installation seems to be broken. In particular, 'config_vars.mk' is missing.
+Please read link:http://forum.mamp.info/viewtopic.php?t=1866[this forum topic] to learn how
+to fix this problem.
+
+See also link:http://code.google.com/p/phusion-passenger/issues/detail?id=12[this bug report].
+
+
+=== Problems during installation ===
+
+[[installing_ruby_dev]]
+==== Ruby development headers aren't installed ====
+
+.Symptoms
+*******************************************************************************
+Installing Phusion Passenger fails because of one of the following errors:
+
+- The Phusion Passenger installer tells you that the Ruby development headers
+  aren't installed.
+- The error message ``'no such file to load -- mkmf''' occurs.
+- The error message ``'ruby.h: No such file or directory''' occurs.
+*******************************************************************************
+
+Phusion Passenger makes use of a native extension, so the Ruby development headers
+must be installed. On most Linux systems, Ruby and the Ruby development headers
+are contained in separate packages, so having Ruby installed does not
+automatically imply having the development headers installed.
+
+Here's how you can install the development headers:
+
+Ubuntu/Debian::
+	Please type:
++
+-----------------------------------------
+sudo apt-get install ruby1.8-dev
+-----------------------------------------
+
+Fedora/CentOS/RHEL::
+	Please type:
++
+-----------------------------------------
+su -c 'yum install ruby-devel'
+-----------------------------------------
+
+FreeBSD::
+	Please install Ruby from 'ports' or with `pkg_add`. If that fails,
+	please install Ruby from source.
+
+MacOS X::
+	Please install Ruby from source.
+
+Other operating systems::
+	Please consult your operating system's native package database.
+	There should be a package containing the Ruby development headers.
+	If that fails, please install Ruby from source.
+
+NOTE: If you've installed a new Ruby version (i.e. your system now contains
+multiple Ruby installations), then you will need to tell Phusion Passenger
+which Ruby installation you want to use. Please read
+<<specifying_ruby_installation,Specifying the correct Ruby installation>>.
+
+==== Apache development headers aren't installed ====
+
+.Symptoms
+*******************************************************************************
+Installing Phusion Passenger fails because of one of the following errors:
+
+- The installer says that the Apache development headers aren't installed.
+- The error message ``'httpd.h: No such file or directory''' occurs.
++
+(Instead of 'httpd.h', the message might also be 'http_config.h' or something
+else similar to 'http_*.h'.)
+*******************************************************************************
+
+Ubuntu::
+	Please type:
++
+-----------------------------------------
+sudo apt-get install apache2-prefork-dev
+-----------------------------------------
+
+Debian::
+	Please type:
++
+-----------------------------------------
+sudo apt-get install apache2-dev
+-----------------------------------------
+
+Fedora/CentOS/RHEL::
+	Please type:
++
+--------------------------------
+su -c 'yum install httpd-devel'
+--------------------------------
+
+FreeBSD::
+	Please install Apache from 'ports' or with `pkg_add`. If that fails,
+	please install Apache from source.
+
+MacOS X::
+	Please install Apache from source.
+
+Other operating systems::
+	Please consult your operating system's native package database.
+	There should be a package containing the Apache development headers.
+	If that fails, please install Apache from source.
+
+
+==== APR development headers aren't installed ====
+
+.Symptoms
+*******************************************************************************
+Installing Phusion Passenger fails because one of the following errors:
+
+- The installer tells you that APR development headers aren't installed.
+- The error message ``'apr_pools.h: No such file or directory''' occurs.
+- The error message ``'apr_strings.h: No such file or directory''' occurs.
+*******************************************************************************
+
+Ubuntu::
+	Please type:
++
+-----------------------------------------
+sudo apt-get install libapr1-dev
+-----------------------------------------
+
+Debian::
+	Please type:
++
+-----------------------------------------
+sudo apt-get install libapr1-dev
+-----------------------------------------
+
+Fedora/CentOS/RHEL::
+	Please type:
++
+--------------------------------
+su -c 'yum install apr-devel'
+--------------------------------
+
+Other Linux distributions::
+	Please consult your distribution's package database. There should be a
+	package which provides APR development headers.
+
+Other operating systems::
+	The APR development are bundled with Apache. If the APR headers aren't,
+	then it probably means that they have been removed after Apache's been
+	installed. Please reinstall Apache to get back the APR headers.
+
+
+==== Phusion Passenger is using the wrong Apache during installation ====
+
+Please <<specifying_correct_apache_install,Specifying the correct Apache
+installation>>, and re-run the Phusion Passenger installer.
+
+
+==== Phusion Passenger is using the wrong Ruby during installation ====
+
+Please <<specifying_ruby_installation,Specifying the correct Ruby
+installation>>, and re-run the Phusion Passenger installer.
+
+
+=== Problems after installation ===
+
+[TIP]
+.The golden tip: read your Apache error logs!
+=====================================================
+'mod_passenger' will write all errors to the Apache error log. So if
+you're experiencing post-installation problems, please look
+inside the Apache error logs. It will tell you what exactly went wrong.
+=====================================================
+
+==== My Rails application works on Mongrel, but not on Phusion Passenger ====
+
+Please try setting <<RailsSpawnMethod,RailsSpawnMethod>> to 'conservative'.
+
+==== Phusion Passenger has been compiled against the wrong Apache installation ====
+
+.Symptoms
+*******************************************************************************
+Apache crashes during startup (after being daemonized). The Apache error log
+says ``'seg fault or similar nasty error detected in the parent process'''.
+*******************************************************************************
+
+This problem is most likely to occur on MacOS X. Most OS X users have multiple
+Apache installations on their system.
+
+To solve this problem, please <<specifying_correct_apache_install,specify the
+correct Apache installation>>, and <<install_passenger,reinstall Phusion
+Passenger>>.
+
+==== I get a "304 Forbidden" error ====
+
+See next subsection.
+
+==== Static assets such as images and stylesheets aren't being displayed ====
+
+Static assets are accelerated, i.e. they are served directly by Apache and do not
+go through the Rails stack. There are two reasons why Apache doesn't serve static
+assets correctly:
+
+1. Your Apache configuration is too strict, and does not allow HTTP clients to
+   access static assets. This can be achieved with an `Allow from all` directive
+   in the correct place. For example:
++
+-----------------------------------------
+<Directory "/webapps/mycook/public">
+   Options FollowSymLinks
+   AllowOverride None
+   Order allow,deny
+   Allow from all
+</Directory>
+-----------------------------------------
++
+See also link:http://groups.google.com/group/phusion-passenger/browse_thread/thread/9699a639a87f85f4/b9d71a03bf2670a5[this discussion].
+
+2. The Apache process doesn't have permission to access your Rails application's folder.
+   Please make sure that the Rails application's folder, as well as all of its parent folders,
+   have the correct permissions and/or ownerships.
+
+==== The Apache error log says that the spawn manager script does not exist, or that it does not have permission to execute it ====
+
+If you are sure that the 'PassengerRoot' configuration option is set correctly,
+then this problem is most likely caused by the fact that you're running Apache
+with SELinux. On Fedora, CentOS and RedHat Enterprise Linux, Apache is locked
+down by SELinux policies.
+
+To solve this problem, you must set some permissions on the Phusion Passenger files
+and folders, so that Apache can access them.
+
+- If you've installed Phusion Passenger via a gem, then run this command to determine
+  Phusion Passenger's root folder:
++
+------------------------------------------------------------------
+passenger-config --root
+------------------------------------------------------------------
++
+Next, run the following command:
++
+------------------------------------------------------------------
+chcon -R -h -t httpd_sys_content_t /path-to-passenger-root
+------------------------------------------------------------------
++
+where '/path-to-passenger-root' should be replaced with whatever
+`passenger-config --root` printed.
+
+- If you've installed Phusion Passenger via the source tarball, then run the following
+  command:
++
+------------------------------------------------------------------
+chcon -R -h -t httpd_sys_content_t /path/to/passenger/folder
+------------------------------------------------------------------
+
+Once the permissions are fixed, restart Apache.
+
+==== The Rails application reports that it's unable to start because of a permission error ====
+
+Please check whether your Rails application's folder has the correct
+permissions. By default, Rails applications are started as the owner of the
+file 'config/environment.rb', except if the file is owned by root. If the
+file is owned by root, then the Rails application will be started as 'nobody'
+(or as the user specify by <<RailsDefaultUser,RailsDefaultUser>>, if that's
+specified).
+
+Please read <<user_switching,User switching (security)>> for details.
+
+==== My Rails application's log file is not being written to ====
+
+There are a couple things that you should be aware of:
+
+- By default, Phusion Passenger runs Rails applications in 'production' mode,
+  so please be sure to check 'production.log' instead of 'development.log'. See
+  <<RailsEnv,RailsEnv>> for configuration.
+- By default, Phusion Passenger runs Rails applications as the owner of 'environment.rb'.
+  So the log file can only be written to if that user has write permission to the
+  log file. Please 'chmod' or 'chown' your log file accordingly.
++
+See <<User_switching,User switching (security)>> for details.
+
+If you're using a RedHat-derived Linux distribution (such as Fedora or CentOS)
+then it is link:http://code.google.com/p/phusion-passenger/issues/detail?id=4[possible
+that SELinux is interfering]. RedHat's SELinux policy only allows Apache to read/write
+directories that have the 'httpd_sys_content_t' security context. Please run the
+following command to give your Rails application folder that context:
+
+-----------------------------------------------------------
+chcon -R -h -t httpd_sys_content_t /path/to/your/rails/app
+-----------------------------------------------------------
+
+
+[[conflicting_apache_modules]]
+=== Conflicting Apache modules ===
+
+==== mod_userdir ====
+
+'mod_userdir' is not compatible with Phusion Passenger at the moment.
+
+==== VirtualDocumentRoot ====
+
+VirtualDocumentRoot is not compatible with Phusion Passenger at the moment.
+
+
+== Analysis and system maintenance tools ==
+
+Phusion Passenger provides a set of tools, which are useful for system analysis,
+maintenance and troubleshooting.
+
+
+=== Inspecting memory usage ===
+
+Process inspection tools such as `ps` and `top` are useful, but they
+link:http://groups.google.com/group/phusion-passenger/msg/1fd1c233456d3180[rarely show the correct memory usage].
+The real memory usage is usually lower than what `ps` and `top` report.
+
+There are many technical reasons why this is so, but an explanation is beyond
+the scope of this Users Guide. We kindly refer the interested reader to
+operating systems literature about 'virtual memory' and 'copy-on-write'.
+
+The tool `passenger-memory-stats` allows one to easily analyze Phusion Passenger's
+and Apache's real memory usage. For example:
+
+-------------------------------------------------------
+[bash@localhost root]# passenger-memory-stats
+------------- Apache processes --------------.
+PID    PPID  Threads  VMSize   Private  Name
+---------------------------------------------.
+5947   1     9        90.6 MB  0.5 MB   /usr/sbin/apache2 -k start
+5948   5947  1        18.9 MB  0.7 MB   /usr/sbin/fcgi-pm -k start
+6029   5947  1        42.7 MB  0.5 MB   /usr/sbin/apache2 -k start
+6030   5947  1        42.7 MB  0.5 MB   /usr/sbin/apache2 -k start
+6031   5947  1        42.5 MB  0.3 MB   /usr/sbin/apache2 -k start
+6033   5947  1        42.5 MB  0.4 MB   /usr/sbin/apache2 -k start
+6034   5947  1        50.5 MB  0.4 MB   /usr/sbin/apache2 -k start
+23482  5947  1        82.6 MB  0.4 MB   /usr/sbin/apache2 -k start
+### Processes: 8
+### Total private dirty RSS: 3.50 MB
+
+--------- Passenger processes ---------.
+PID    Threads  VMSize   Private  Name
+---------------------------------------.
+6026   1        10.9 MB  4.7 MB   Passenger spawn server
+23481  1        26.7 MB  3.0 MB   Passenger FrameworkSpawner: 2.0.2
+23791  1        26.8 MB  2.9 MB   Passenger ApplicationSpawner: /var/www/projects/app1-foobar
+23793  1        26.9 MB  17.1 MB  Rails: /var/www/projects/app1-foobar
+### Processes: 4
+### Total private dirty RSS: 27.76 M
+-------------------------------------------------------
+
+The 'Private' or 'private dirty RSS' field shows the *real* memory usage of processes. Here,
+we see that all the Apache worker processes only take less than 1 MB memory each.
+This is a lot less than the 50 MB-ish memory usage as shown in the 'VMSize' column
+(which is what a lot of people think is the real memory usage, but is actually not).
+
+NOTE: This tool only works on Linux. Unfortunately other operating systems don't
+provide facilities for determining processes' private dirty RSS.
+
+
+=== Inspecting Phusion Passenger's internal status ===
+
+One can inspect Phusion Passenger's internal status with the tool `passenger-status`.
+This tool must typically be run as root. For example:
+
+--------------------------------------------------
+[bash@localhost root]# passenger-status
+----------- General information -----------
+max      = 6
+count    = 1
+active   = 0
+inactive = 1
+
+----------- Domains -----------
+/var/www/projects/app1-foobar: 
+  PID: 9617      Sessions: 0    Processed: 7       Uptime: 2m 23s
+--------------------------------------------------
+
+The 'general information' section shows the following information:
+
+max:: The maximum number of application instances that Phusion Passenger will
+spawn. This equals the value given for <<PassengerMaxPoolSize,PassengerMaxPoolSize>>.
+count:: The number of application instances that are currently alive. This value
+is always less than or equal to 'max'.
+active:: The number of application instances that are currently processing
+requests. This value is always less than or equal to 'count'.
+inactive:: The number of application instances that are currently *not* processing
+requests, i.e. are idle. Idle application instances will be shutdown after a while,
+as can be specified with <<PassengerPoolIdleTime,PassengerPoolIdleTime>> (unless this
+value is set to 0, in which case application instances are never shut down via idle
+time). The value of 'inactive' equals `count - active`.
+
+The 'domains' section shows, for each application directory, information about running
+application instances:
+
+Sessions:: Shows how many HTTP client are currently in the queue of that application
+Instance, waiting to be processed.
+Processed:: Indicates how many requests the instance has served until now. *Tip:* it's
+possible to limit this number with the <<PassengerMaxRequests,PassengerMaxRequests>>
+configuration directive.
+Uptime:: Shows for how long the application instance has been running.
+
+Since Phusion Passenger uses fair load balancing by default, the number of sessions for the
+application instances should be fairly close to each other. For example, this is fairly
+normal:
+--------------------------------
+  PID: 4281      Sessions: 2      Processed: 7      Uptime: 5m 11s
+  PID: 4268      Sessions: 0      Processed: 5      Uptime: 4m 52s
+  PID: 4265      Sessions: 1      Processed: 6      Uptime: 5m 38s
+  PID: 4275      Sessions: 1      Processed: 7      Uptime: 3m 14s
+--------------------------------
+
+But if you see a "spike", i.e. an application instance has an unusually high number of
+sessions compared to the others, then there might be a problem:
+--------------------------------
+  PID: 4281      Sessions: 2      Processed: 7      Uptime: 5m 11s
+  PID: 17468     Sessions: 8 <-+  Processed: 2      Uptime: 4m 47s
+  PID: 4265      Sessions: 1   |  Processed: 6      Uptime: 5m 38s
+  PID: 4275      Sessions: 1   |  Processed: 7      Uptime: 3m 14s
+                               |
+                               +---- "spike"
+--------------------------------
+
+Possible reasons why spikes can occur:
+
+. Your application is busy processing a request that takes a very long time.
+  If this is the case, then you might want to turn
+  <<PassengerUseGlobalQueue,global queuing>> on.
+. Your application is frozen, i.e. has stopped responding. See
+  <<debugging_frozen,Debugging frozen applications>> for tips.
+
+
+[[debugging_frozen]]
+=== Debugging frozen applications ===
+
+If one of your application instances is frozen (stopped responding), then you
+can figure out where it is frozen by killing it with 'SIGABRT'. This will cause the
+application to raise an exception, with a backtrace.
+
+The exception (with full backtrace information) is normally logged into the Apache
+error log. But if your application or if its web framework has its own exception logging
+routines, then exceptions might be logged into the application's log files instead.
+This is the case with Ruby on Rails. So if you kill a Ruby on Rails application with
+'SIGABRT', please check the application's 'production.log' first (assuming that you're
+running it in a 'production' environment). If you don't see a backtrace there, check
+the Apache error log.
+
+NOTE: It is safe to kill application instances, even in live environments. Phusion Passenger
+will restart killed application instances, as if nothing bad happened.
+
+
+== Tips ==
+
+[[user_switching]]
+=== User switching (security) ===
+
+There is a problem that plagues most PHP web hosts, namely the fact that all PHP
+applications are run in the same user context as the web server. So for
+example, Joe's PHP application will be able to read Jane's PHP application's
+passwords. This is obviously undesirable on many servers.
+
+Phusion Passenger solves this problem by implementing 'user switching'. A Rails
+application is started as the owner of the file 'config/environment.rb',
+and a Rack application is started as the owner of the file 'config.ru'.
+So if '/home/webapps/foo/config/environment.rb' is owned by 'joe', then Phusion
+Passenger will launch the corresponding Rails application as 'joe' as well.
+
+This behavior is the default, and you don't need to configure anything. But
+there are things that you should keep in mind:
+
+- The owner of 'environment.rb' must have read access to the Rails application's
+  folder, and read/write access to the Rails application's 'logs' folder.
+  Likewise, the owner of 'config.ru' must have read access to the Rack application's
+  folder.
+- This feature is only available if Apache is started by 'root'. This is the
+  case on most Apache installations.
+- Under no circumstances will applications be run as 'root'. If
+  'environment.rb'/'config.ru' is owned as root or by an unknown user, then the
+  Rails/Rack application will run as the user specified by
+  <<PassengerDefaultUser,PassengerDefaultUser>>.
+
+User switching can be disabled with the
+<<PassengerUserSwitching,PassengerUserSwitching>> option.
+
+
+[[reducing_memory_usage]]
+=== Reducing memory consumption of Ruby on Rails applications by 33% ===
+
+Is it possible to reduce memory consumption of your Rails applications by 33% on average,
+by using http://www.rubyenterpriseedition.com/[Ruby Enterprise Edition].
+Please visit the website for details.
+
+Note that this feature does not apply to Rack applications.
+
+[[capistrano]]
+=== Capistrano recipe ===
+
+Phusion Passenger can be combined with link:http://capify.org/[Capistrano].
+The following Capistrano recipe demonstrates Phusion Passenger support.
+It assumes that you're using Git as version control system.
+
+--------------------------------------------------
+set :application, "myapp"
+set :domain,      "example.com"
+set :repository,  "ssh://#{domain}/path-to-your-git-repo/#{application}.git"
+set :use_sudo,    false
+set :deploy_to,   "/path-to-your-web-app-directory/#{application}"
+set :scm,         "git"
+
+role :app, domain
+role :web, domain
+role :db,  domain, :primary => true
+
+namespace :deploy do
+  task :start, :roles => :app do
+    run "touch #{current_release}/tmp/restart.txt"
+  end
+  
+  task :stop, :roles => :app do
+    # Do nothing.
+  end
+  
+  desc "Restart Application"
+  task :restart, :roles => :app do
+    run "touch #{current_release}/tmp/restart.txt"
+  end
+end
+--------------------------------------------------
+
+You may notice that after each deploy, a new spawner server is
+created (it'll show up in `passenger-memory-stats`). Indeed, Capistrano will deploy
+to a path ending with '/current' (ie : '/u/apps/yourapp/current'), so that you don't
+have to care about revisions in your virtual host configuration. This '/current' directory
+is a symlink to the current revision deployed ('/path_to_app/releases/date_of_the_release').
+Phusion Passenger recognizes applications by their full canonical path, so after
+deploying a new version, Phusion Passenger will think that the new version is
+a totally different application, thereby creating a new spawner server:
+
+--------------------------------------------------
+1001   30291   [...]   Passenger ApplicationSpawner: /u/apps/my_app/releases/20080509104413
+1001   31371   [...]   Passenger ApplicationSpawner: /u/apps/my_app/releases/20080509104632
+--------------------------------------------------
+
+Don't worry about this. The (old) spawner server will terminate itself after its
+timeout period (10 minutes by default), so you will not run out of memory.
+
+If you really want to release the spawner server's memory immediately, then you can add a command
+to your Capistrano script to terminate the Passenger spawn server after each deploy. That
+command is as follows:
+
+--------------------------------------------------
+kill $( passenger-memory-stats | grep 'Passenger spawn server' | awk '{ print $1 }' )
+--------------------------------------------------
+
+Killing the spawn server is completely safe, because Phusion Passenger will restart the
+spawn server if it has been terminated.
+
+
+=== Moving Phusion Passenger to a different directory ===
+
+It is possible to relocate the Phusion Passenger files to a different directory. It
+involves two steps:
+
+1. Moving the directory.
+2. Updating the ``PassengerRoot'' configuration option in Apache.
+
+For example, if Phusion Passenger is located in '/opt/passenger/', and you'd like to
+move it to '/usr/local/passenger/', then do this:
+
+1. Run the following command:
++
+------------------------------------
+mv /opt/passenger /usr/local/passenger
+------------------------------------
+2. Edit your Apache configuration file, and set:
++
+------------------------------------
+PassengerRoot /usr/local/passenger
+------------------------------------
+
+=== Installing multiple Ruby on Rails versions ===
+
+Each Ruby on Rails applications that are going to be deployed may require a
+specific Ruby on Rails version. You can install a specific version with
+this command:
+-----------------------------
+gem install rails -v X.X.X
+-----------------------------
+where 'X.X.X' is the version number of Ruby on Rails.
+
+All of these versions will exist in parallel, and will not conflict with each
+other. Phusion Passenger will automatically make use of the correct version.
+
+=== X-Sendfile support ===
+
+Phusion Passenger does not provide X-Sendfile support by itself. Please install
+link:http://tn123.ath.cx/mod_xsendfile/[mod_xsendfile] for X-Sendfile support.
+
+=== Upload progress ===
+
+Phusion Passenger does not provide upload progress support by itself. Please
+try drogus's link:http://github.com/drogus/apache-upload-progress-module/tree/master[
+Apache upload progress module] instead.
+
+=== Making the application restart after each request ===
+
+In some situations it might be desirable to restart the web application after
+each request, for example when developing a non-Rails application that doesn't
+support code reloading, or when developing a web framework.
+
+To achieve this, simply create the file 'tmp/always_restart.txt' in your
+application's root folder. Unlike 'restart.txt', Phusion Passenger does not
+delete this file. If both files are present ('restart.txt' and 'always_restart.txt'),
+then Phusion Passenger will still restart the application, but won't delete
+'restart.txt'.
+
+NOTE: If you're just developing a Rails application then you probably don't need
+this feature. If you set 'RailsEnv development' in your Apache configuration,
+then Rails will automatically reload your application code after each request.
+'always_restart.txt' is only useful if you're working on Ruby on Rails itself,
+or when you're not developing a Rails application and your web framework
+does not support code reloading.
+
+== Appendix A: About this document ==
+
+The text of this document is licensed under the
+link:http://creativecommons.org/licenses/by-sa/3.0/[Creative Commons
+Attribution-Share Alike 3.0 Unported License].
+
+image:images/by_sa.png[link="http://creativecommons.org/licenses/by-sa/3.0/"]
+
+Phusion Passenger is brought to you by link:http://www.phusion.nl/[Phusion].
+
+image:images/phusion_banner.png[link="http://www.phusion.nl/"]
+
+Phusion Passenger is a trademark of Hongli Lai & Ninh Bui.
+
+== Appendix B: Terminology ==
+
+[[application_root]]
+=== Application root ===
+The root directory of an application that's served by Phusion Passenger.
+
+In case of Ruby on Rails applications, this is the directory that contains
+'Rakefile', 'app/', 'config/', 'public/', etc. In other words, the directory
+pointed to by `RAILS_ROOT`. For example, take the following directory structure:
+
+-----------------------------------------
+/apps/foo/       <------ This is the Rails application's application root!
+   |
+   +- app/
+   |   |
+   |   +- controllers/
+   |   |
+   |   +- models/
+   |   |
+   |   +- views/
+   |
+   +- config/
+   |   |
+   |   +- environment.rb
+   |   |
+   |   +- ...
+   |
+   +- public/
+   |   |
+   |   +- ...
+   |
+   +- ...
+-----------------------------------------
+
+In case of Rack applications, this is the directory that contains 'config.ru'.
+For example, take the following directory structure:
+
+-----------------------------------------
+/apps/bar/      <----- This is the Rack application's application root!
+   |
+   +- public/
+   |    |
+   |    +- ...
+   |
+   +- config.ru
+   |
+   +- ...
+-----------------------------------------
+
+In case of Python (WSGI) applications, this is the directory that contains
+'passenger_wsgi.py'. For example, take the following directory structure:
+
+-----------------------------------------
+/apps/baz/      <----- This is the WSGI application's application root!
+   |
+   +- public/
+   |    |
+   |    +- ...
+   |
+   +- passenger_wsgi.py
+   |
+   +- ...
+-----------------------------------------
+
+
+[[spawning_methods_explained]]
+== Appendix C: Spawning methods explained ==
+
+At its core, Phusion Passenger is an HTTP proxy and process manager. It spawns
+Ruby on Rails/Rack/WSGI worker processes (which may also be referred to as
+'backend processes'), and forwards incoming HTTP request to one of the worker
+processes.
+
+While this may sound simple, there's not just one way to spawn worker processes.
+Let's go over the different spawning methods. For simplicity's sake, let's
+assume that we're only talking about Ruby on Rails applications.
+
+=== The most straightforward and traditional way: conservative spawning ===
+
+Phusion Passenger could create a new Ruby process, which will then load the
+Rails application along with the entire Rails framework. This process will then
+enter an request handling main loop.
+
+This is the most straightforward way to spawn worker processes. If you're
+familiar with the Mongrel application server, then this approach is exactly
+what mongrel_cluster performs: it creates N worker processes, each which loads
+a full copy of the Rails application and the Rails framework in memory. The Thin
+application server employs pretty much the same approach.
+
+Note that Phusion Passenger's version of conservative spawning differs slightly
+from mongrel_cluster. Mongrel_cluster creates entirely new Ruby processes. In
+programmers jargon, mongrel_cluster creates new Ruby processes by forking the
+current process and exec()-ing a new Ruby interpreter. Phusion Passenger on the
+other hand creates processes that reuse the already loaded Ruby interpreter. In
+programmers jargon, Phusion Passenger calls fork(), but not exec().
+
+=== The smart spawning method ===
+
+NOTE: Smart spawning is only available for Ruby on Rails applications, not for
+      Rack applications or WSGI applications.
+
+While conservative spawning works well, it's not as efficient as it could be
+because each worker process has its own private copy of the Rails application
+as well as the Rails framework. This wastes memory as well as startup time.
+
+image:images/conservative_spawning.png[Worker processes and conservative spawning] +
+'Figure: Worker processes and conservative spawning. Each worker process has its
+own private copy of the application code and Rails framework code.'
+
+It is possible to make the different worker processes share the memory occupied
+by application and Rails framework code, by utilizing so-called
+copy-on-write semantics of the virtual memory system on modern operating
+systems. As a side effect, the startup time is also reduced. This is technique
+is exploited by Phusion Passenger's 'smart' and 'smart-lv2' spawn methods.
+
+==== How it works ====
+
+When the 'smart-lv2' spawn method is being used, Phusion Passenger will first
+create a so-called 'ApplicationSpawner server' process. This process loads the
+entire Rails application along with the Rails framework, by loading
+'environment.rb'. Then, whenever Phusion Passenger needs a new worker process,
+it will instruct the ApplicationSpawner server to do so. The ApplicationSpawner
+server will create a worker new process
+that reuses the already loaded Rails application/framework. Creating a worker
+process through an already running ApplicationSpawner server is very fast, about
+10 times faster than loading the Rails application/framework from scratch. If
+the Ruby interpreter is copy-on-write friendly (that is, if you're running
+<<reducing_memory_usage,Ruby Enterprise Edition>>) then all created worker
+processes will share as much common
+memory as possible. That is, they will all share the same application and Rails
+framework code.
+
+image:images/smart-lv2.png[] +
+'Figure: Worker processes and the smart-lv2 spawn method. All worker processes,
+as well as the ApplicationSpawner, share the same application code and Rails
+framework code.'
+
+The 'smart' spawn method goes even further, by caching the Rails framework in
+another process called the 'FrameworkSpawner server'. This process only loads
+the Rails framework, not the application. When a FrameworkSpawner server is
+instructed to create a new worker process, it will create a new
+ApplicationSpawner to which the instruction will be delegated. All those
+ApplicationSpawner servers, as well as all worker processes created by those
+ApplicationSpawner servers, will share the same Rails framework code.
+
+The 'smart-lv2' method allows different worker processes that belong to the same
+application to share memory. The 'smart' method allows different worker
+processes - that happen to use the same Rails version - to share memory, even if
+they don't belong to the same application.
+
+Notes:
+
+- Vendored Rails frameworks cannot be shared by different applications, even if
+  both vendored Rails frameworks are the same version. So for efficiency reasons
+  we don't recommend vendoring Rails.
+- ApplicationSpawner and FrameworkSpawner servers have an idle timeout just
+  like worker processes. If an ApplicationSpawner/FrameworkSpawner server hasn't
+  been instructed to do anything for a while, it will be shutdown in order to
+  conserve memory. This idle timeout is configurable.
+
+==== Summary of benefits ====
+
+Suppose that Phusion Passenger needs a new worker process for an application
+that uses Rails 2.2.1.
+
+- If the 'smart-lv2' spawning method is used, and an ApplicationSpawner server
+  for this application is already running, then worker process creation time is
+  about 10 times faster than conservative spawning. This worker process will also
+  share application and Rails framework code memory with the ApplicationSpawner
+  server and the worker processes that had been spawned by this ApplicationSpawner
+  server.
+- If the 'smart' spawning method is used, and a FrameworkSpawner server for
+  Rails 2.2.1 is already running, but no ApplicationSpawner server for this
+  application is running, then worker process creation time is about 2 times
+  faster than conservative spawning. If there is an ApplicationSpawner server
+  for this application running, then worker process creation time is about 10
+  times faster. This worker process will also share application and Rails
+  framework code memory with the ApplicationSpawner and FrameworkSpawner
+  servers.
+
+You could compare ApplicationSpawner and FrameworkSpawner servers with stem
+cells, that have the ability to quickly change into more specific cells (worker
+process).
+
+In practice, the smart spawning methods could mean a memory saving of about 33%,
+assuming that your Ruby interpreter is <<reducing_memory_usage,copy-on-write friendly>>.
+
+Of course, smart spawning is not without gotchas. But if you understand the
+gotchas you can easily reap the benefits of smart spawning.
+
+=== Smart spawning gotcha #1: unintential file descriptor sharing ===
+
+Because worker processes are created by forking from an ApplicationSpawner
+server, it will share all file descriptors that are opened by the
+ApplicationSpawner server. (This is part of the semantics of the Unix
+'fork()' system call. You might want to Google it if you're not familiar with
+it.) A file descriptor is a handle which can be an opened file, an opened socket
+connection, a pipe, etc. If different worker processes write to such a file
+descriptor at the same time, then their write calls will be interleaved, which
+may potentially cause problems.
+
+The problem commonly involves socket connections that are unintentially being
+shared. You can fix it by closing and reestablishing the connection when Phusion
+Passenger is creating a new worker process. Phusion Passenger provides the API
+call `PhusionPassenger.on_event(:starting_worker_process)` to do so. So you
+could insert the following code in your 'environment.rb':
+
+[source, ruby]
+-----------------------------------------
+if defined?(PhusionPassenger)
+    PhusionPassenger.on_event(:starting_worker_process) do |forked|
+        if forked
+            # We're in smart spawning mode.
+            ... code to reestablish socket connections here ...
+        else
+            # We're in conservative spawning mode. We don't need to do anything.
+        end
+    end
+end
+-----------------------------------------
+
+Note that Phusion Passenger automatically reestablishes the connection to the
+database upon creating a new worker process, which is why you normally do not
+encounter any database issues when using smart spawning mode.
+
+==== Example 1: Memcached connection sharing (harmful) ====
+
+Suppose we have a Rails application that connects to a Memcached server in
+'environment.rb'. This causes the ApplicationSpawner to have a socket connection
+(file descriptor) to the Memcached server, as shown in the following figure:
+
+ +--------------------+
+ | ApplicationSpawner |-----------[Memcached server]
+ +--------------------+
+
+Phusion Passenger then proceeds with creating a new Rails worker process, which
+is to process incoming HTTP requests. The result will look like this:
+
+ +--------------------+
+ | ApplicationSpawner |------+----[Memcached server]
+ +--------------------+      |
+                             |
+ +--------------------+      |
+ | Worker process 1   |-----/
+ +--------------------+
+
+Since a 'fork()' makes a (virtual) complete copy of a process, all its file
+descriptors will be copied as well. What we see here is that ApplicationSpawner
+and Worker process 1 both share the same connection to Memcached.
+
+Now supposed that your site gets Slashdotted and Phusion Passenger needs to
+spawn another worker process. It does so by forking ApplicationSpawner. The
+result is now as follows:
+
+ +--------------------+
+ | ApplicationSpawner |------+----[Memcached server]
+ +--------------------+      |
+                             |
+ +--------------------+      |
+ | Worker process 1   |-----/|
+ +--------------------+      |
+                             |
+ +--------------------+      |
+ | Worker process 2   |-----/
+ +--------------------+
+
+As you can see, Worker process 1 and Worker process 2 have the same Memcache
+connection.
+
+Suppose that users Joe and Jane visit your website at the same time. Joe's
+request is handled by Worker process 1, and Jane's request is handled by Worker
+process 2. Both worker processes want to fetch something from Memcached. Suppose
+that in order to do that, both handlers need to send a "FETCH" command to Memcached.
+
+But suppose that, after worker process 1 having only sent "FE", a context switch
+occurs, and worker process 2 starts sending a "FETCH" command to Memcached as
+well. If worker process 2 succeeds in sending only one bye, 'F', then Memcached
+will receive a command which begins with "FEF", a command that it does not
+recognize. In other words: the data from both handlers get interleaved. And thus
+Memcached is forced to handle this as an error.
+
+This problem can be solved by reestablishing the connection to Memcached after forking:
+
+ +--------------------+
+ | ApplicationSpawner |------+----[Memcached server]
+ +--------------------+      |                   |
+                             |                   |
+ +--------------------+      |                   |
+ | Worker process 1   |-----/|                   |
+ +--------------------+      |                   |  <--- created this
+                             X                   |       new
+                                                 |       connection
+                             X <-- closed this   |
+ +--------------------+      |     old           |
+ | Worker process 2   |-----/      connection    |
+ +--------------------+                          |
+           |                                     |
+           +-------------------------------------+
+
+Worker process 2 now has its own, separate communication channel with Memcached.
+The code in 'environment.rb' looks like this:
+
+[source, ruby]
+-----------------------------------------
+if defined?(PhusionPassenger)
+    PhusionPassenger.on_event(:starting_worker_process) do |forked|
+        if forked
+            # We're in smart spawning mode.
+            reestablish_connection_to_memcached
+        else
+            # We're in conservative spawning mode. We don't need to do anything.
+        end
+    end
+end
+-----------------------------------------
+
+==== Example 2: Log file sharing (not harmful) ====
+
+There are also cases in which unintential file descriptor sharing is not harmful.
+One such case is log file file descriptor sharing. Even if two processes write
+to the log file at the same time, the worst thing that can happen is that the
+data in the log file is interleaved.
+
+To guarantee that the data written to the log file is never interleaved, you
+must synchronize write access via an inter-process synchronization mechanism,
+such as file locks. Reopening the log file, like you would have done in the
+Memcached example, doesn't help.
+
+=== Smart spawning gotcha #2: the need to revive threads ===
+
+Another part of the 'fork()' system call's semantics is the fact that threads
+disappear after a fork call. So if you've created any threads in environment.rb,
+then those threads will no longer be running in newly created worker process.
+You need to revive them when a new worker process is created. Use the
+`:starting_worker_process` event that Phusion Passenger provides, like this:
+
+[source, ruby]
+-----------------------------------------
+if defined?(PhusionPassenger)
+    PhusionPassenger.on_event(:starting_worker_process) do |forked|
+        if forked
+            # We're in smart spawning mode.
+            ... code to revive threads here ...
+        else
+            # We're in conservative spawning mode. We don't need to do anything.
+        end
+    end
+end
+-----------------------------------------
+
+=== Smart spawning gotcha #3: code load order ===
+
+This gotcha is only applicable to the 'smart' spawn method, not the 'smart-lv2'
+spawn method.
+
+If your application expects the Rails framework to be not loaded during the
+beginning of 'environment.rb', then it can cause problems when an
+ApplicationSpawner is created from a FrameworkSpawner, which already has the
+Rails framework loaded. The most common case is when applications try to patch
+Rails by dropping a modified file that has the same name as Rails's own file,
+in a path that comes earlier in the Ruby search path.
+
+For example, suppose that we have an application which has a patched version
+of 'active_record/base.rb' located in 'RAILS_ROOT/lib/patches', and
+'RAILS_ROOT/lib/patches' comes first in the Ruby load path. When conservative
+spawning is used, the patched version of 'base.rb' is properly loaded. When
+'smart' (not 'smart-lv2') spawning is used, the original 'base.rb' is used
+because it was already loaded, so a subsequent `require "active_record/base"`
+has no effect.