passenger 2.0.6 → 2.1.2

data/doc/Users guide.txt

@@ -28,6 +28,7 @@ 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)
@@ -131,22 +132,19 @@ 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
-------------------------------------------------------
+John Leach from Brightbox has kindly provided an Ubuntu Hardy package for Phusion Passenger. The package is available from the link:http://apt.brightbox.net[Brightbox repository].
 
-Next, you'll need to configure Apache. Run the "installer", as it will tell you
-the correct configuration options for Apache:
+Please install the native Linux package, e.g.:
 ------------------------------------------------------
-passenger-install-apache2-module
+sudo sh -c 'echo "deb http://apt.brightbox.net hardy main" > /etc/apt/sources.list.d/brightbox.list'
+sudo sh -c 'wget -q -O - http://apt.brightbox.net/release.asc | apt-key add -'
+sudo apt-get update
+sudo apt-get install libapache2-mod-passenger
 ------------------------------------------------------
 
-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 ====
 
@@ -260,8 +258,8 @@ 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.
+   application's <<application_root,root folder>>. Phusion Passenger will
+   automatically restart the application.
 
 For example, to restart our example MyCook application, we type this in the
 command line:
@@ -288,7 +286,7 @@ 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 two entries:
+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.
@@ -419,8 +417,8 @@ 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.
+   application's <<application_root,root folder>>. Phusion Passenger will
+   automatically restart the application.
 
 For example, to restart our example application, we type this in the
 command line:
@@ -472,8 +470,10 @@ run Mack::Utils::Server.build_app
 require 'rubygems'
 require 'merb-core'
 
-Merb::Config.setup(:merb_root   => ".",
-                   :environment => ENV['RACK_ENV'])
+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
@@ -496,14 +496,12 @@ 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
-)
+set :environment, ENV['RACK_ENV'].to_sym
+set :root,        root_dir
+set :app_file,    File.join(root_dir, 'app.rb')
+disable :run
 
-run Sinatra.application
+run Sinatra::Application
 ------------------------------------------------------
 
 
@@ -545,12 +543,43 @@ 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 only occur once, in the global server configuration. The
-default is '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].'
 
@@ -650,6 +679,197 @@ 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
+        AllowOverride all      # <-- Makes Wordpress's .htaccess file work.
+    </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> ====
@@ -705,9 +925,75 @@ 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> ====
@@ -751,23 +1037,25 @@ Used to specify that the given URI is a Rails application. See
 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 global server configuration or in a
-virtual host configuration block.
-
-[[RailsAllowModRewrite]]
-==== RailsAllowModRewrite <on|off> ====
-If enabled, Phusion Passenger will not override mod_rewrite rules. Please read
-<<conflicting_apache_modules,Conflicting Apache modules>> for details.
+This option may occur in the following places:
 
-This option may occur once, in the global server configuration or in a virtual host
-configuration block. The default value is 'off'.
+ * 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 once, in the global server configuration or in a virtual host
-configuration block. The default value is 'production'.
+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> ====
@@ -779,11 +1067,11 @@ understand it, as it's mostly a technical detail. You can basically follow this
 
 ************************************************
 If your application works on Mongrel, but not on Phusion Passenger, then set
-`RailsSpawnMethod` to 'conservative'. Otherwise, leave it at 'smart' (the default).
+`RailsSpawnMethod` to 'conservative'. Otherwise, leave it at 'smart-lv2' (the default).
 ************************************************
 
-However, we do recommend you to try to understand it. The 'smart' spawn method brings
-many benefits.
+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
@@ -792,7 +1080,9 @@ 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.
+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
@@ -803,9 +1093,26 @@ Some Ruby on Rails applications and libraries are not compatible with smart spaw
 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.
+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
@@ -816,8 +1123,52 @@ Much slower than smart spawning. Every spawn action will be equally slow, though
 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 once, in the global server configuration or in a virtual host
-configuration block. The default value is 'smart'.
+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'.
+
+==== RailsFrameworkSpawnerIdleTime <integer> ====
+The FrameworkSpawner server (explained in <<spawning_methods_explained,Spawning
+methods explained>>) has an idle timeout, just like the backend processes spawned by
+Phusion Passenger do. That is, it will automatically shutdown if it hasn't done
+anything for a given period.
+
+This option allows you to set the FrameworkSpawner server's idle timeout, in
+seconds. A value of '0' means that it should never idle timeout.
+
+Setting a higher value will mean that the FrameworkSpawner server is kept around
+longer, which may slightly increase memory usage. But as long as the
+FrameworkSpawner server is running, the time to spawn a Ruby on Rails backend
+process only takes about 40% of the time that is normally needed, assuming that
+you're using the 'smart' <<RailsSpawnMethod,spawning method>>. So if your
+system has enough memory, is it recommended that you set this option to a high
+value or to '0'.
+
+This option may only occur in the global server configuration, and may occur at
+most once. The default value is '1800' (30 minutes).
+
+==== RailsAppSpawnerIdleTime <integer> ====
+The ApplicationSpawner server (explained in <<spawning_methods_explained,Spawning
+methods explained>>) has an idle timeout, just like the backend processes spawned by
+Phusion Passenger do. That is, it will automatically shutdown if it hasn't done
+anything for a given period.
+
+This option allows you to set the ApplicationSpawner server's idle timeout, in
+seconds. A value of '0' means that it should never idle timeout.
+
+Setting a higher value will mean that the ApplicationSpawner server is kept around
+longer, which may slightly increase memory usage. But as long as the
+ApplicationSpawner server is running, the time to spawn a Ruby on Rails backend
+process only takes about 10% of the time that is normally needed, assuming that
+you're using the 'smart' or 'smart-lv2' <<RailsSpawnMethod,spawning method>>. So if your
+system has enough memory, is it recommended that you set this option to a high
+value or to '0'.
+
+This option may only occur in the global server configuration, and may occur at
+most once. The default value is '600' (10 minutes).
 
 === Rack-specific options ===
 
@@ -862,8 +1213,12 @@ Used to specify that the given URI is a Rack application. See
 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 global server configuration or in a
-virtual host configuration block.
+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> ====
@@ -871,8 +1226,14 @@ 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 once, in the global server configuration or in a virtual host
-configuration block. The default value is 'production'.
+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 ===
 
@@ -888,6 +1249,9 @@ 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 ==
 
@@ -1197,34 +1561,6 @@ chcon -R -h -t httpd_sys_content_t /path/to/your/rails/app
 [[conflicting_apache_modules]]
 === Conflicting Apache modules ===
 
-==== mod_rewrite and mod_alias ====
-
-Phusion Passenger conflicts with 'mod_rewrite' and 'mod_alias'. Those modules may be
-installed and loaded together with 'mod_passenger', and they will work fine
-outside virtual hosts that contain a Rails application, but we recommend you
-not to use their features inside virtual hosts that contain a Rails
-application.
-
-By default, Phusion Passenger will override mod_rewrite rules on Rails hosts.
-This is because the default .htaccess, as provided by Ruby on Rails, redirects all
-requests to `dispatch.cgi' using mod_rewrite. This is a CGI application which
-loads the entire Ruby on Rails framework for every request, and thus is very
-slow. If we do not override mod_rewrite, then Ruby on Rails apps will be slow
-on Phusion Passenger by default -- but we want a good out-of-the-box experience.
-
-Furthermore, the primary reason why people use mod_rewrite with Rails
-applications, is to accelerate page caching. Phusion Passenger supports page
-caching out-of-the-box, without mod_rewrite.
-
-It is not fully understood how mod_alias conflicts with Phusion Passenger, but we
-recommend you not to use it on Rails virtual hosts. mod_alias rules can result
-in surprising problems.
-
-If you really want to use mod_rewrite on Rails virtual hosts, then please set
-the <<RailsAllowModRewrite,RailsAllowModRewrite>> configuration option. But
-please note that you will have to delete Rails applications' default .htaccess
-file, or add rewrite rules to negate its effects.
-
 ==== mod_userdir ====
 
 'mod_userdir' is not compatible with Phusion Passenger at the moment.
@@ -1302,9 +1638,9 @@ count    = 1
 active   = 0
 inactive = 1
 
------------ Applications -----------
+----------- Domains -----------
 /var/www/projects/app1-foobar: 
-  PID: 9617      Sessions: 0
+  PID: 9617      Sessions: 0    Processed: 7       Uptime: 2m 23s
 --------------------------------------------------
 
 The 'general information' section shows the following information:
@@ -1317,30 +1653,39 @@ 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>>. The value of 'inactive'
-equals `count - active`.
+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:
 
-The 'applications' section shows each application instance, which directory it belongs
-to. The 'sessions' field shows how many HTTP client are currently being processed by
-that application instance.
+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
-  PID: 4268      Sessions: 0
-  PID: 4265      Sessions: 1
-  PID: 4275      Sessions: 1
+  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
-  PID: 17468     Sessions: 8     <---- "spike"
-  PID: 4265      Sessions: 1
-  PID: 4275      Sessions: 1
+  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:
@@ -1376,7 +1721,7 @@ will restart killed application instances, as if nothing bad happened.
 [[user_switching]]
 === User switching (security) ===
 
-There is a problem that plagues most PHP web host, namely the fact that all PHP
+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.
@@ -1434,30 +1779,37 @@ 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_path}/tmp/restart.txt"
+    run "touch #{current_release}/tmp/restart.txt"
   end
 end
 --------------------------------------------------
 
-[NOTE]
-==========================================================================
-You may notice that for each deploy, a new spawner server is
+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 : '/var/www/yourapp/current'), so that you don't
+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').
-Therefore, when deploying a new version, the symlink will change, and Phusion Passenger
-will think it's a new application, thereby creating a new spawner server:
+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: /var/www/my_app/releases/20080509104413
-1001   31371   [...]   Passenger ApplicationSpawner: /var/www/my_app/releases/20080509104632
+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 default
-timeout (10 minutes), so you will not run out of memory.
+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
@@ -1469,7 +1821,7 @@ 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 ===
 
@@ -1517,6 +1869,23 @@ 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
+check for this file's timestamp: Phusion Passenger will always restart the
+application, as long as 'always_restart.txt' exists.
+
+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 ==
 
@@ -1532,3 +1901,372 @@ 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.