passenger 2.2.2 → 2.2.3

data/doc/Users guide Apache.txt

@@ -24,35 +24,26 @@ using the commandline.
 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
+Phusion Passenger is confirmed on a large number of operating systems and Linux
+distributions, including, but not limited to, Ubuntu, Debian, CentOS/Fedora/RHEL,
+Gentoo, Mac OS X, FreeBSD and Solaris. Both 32-bit and 64-bit platforms are supported.
+
+The only POSIX-compliant operating system on which Phusion Passenger for Apache is
+known not to work at this time, is OpenBSD. Please use Phusion Passenger for Nginx
+instead.
+
+If Phusion Passenger does not work on your platform then 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.
+link:http://groups.google.com/group/phusion-passenger[join our discussion list].
 
 
-== Installing Phusion Passenger ==
+== Installing, upgrading and uninstalling Phusion Passenger ==
 
 === Generic installation instructions ===
 
 [[install_passenger]]
-==== Overview of download and installation methods ====
+==== Overview of installation methods ====
 
 There are three ways to install Phusion Passenger:
 
@@ -61,39 +52,73 @@ There are three ways to install Phusion Passenger:
    Passenger website].
 2. By downloading the source tarball from the Phusion Passenger website
    ('passenger-x.x.x.tar.gz').
-3. By downloading a native Linux package (e.g. Debian package) from the
-   Phusion Passenger website.
-
-In our opinion, installing the gem or the native package is easiest.
+3. By installing a native Linux package (e.g. Debian package).
 
-Phusion Passenger provides an easy-to-use installer for installing the Phusion
-Passenger Apache module, in case you choose to install via the gem or the
-source tarball.
+The following sections will explain each installation method. Please read the
+section for the installation method that you prefer. In our opinion, installing
+the gem or the native package is easiest. For these two installation methods,
+Phusion Passenger provides an easy-to-use installer.
 
-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.
-
-==== Preparation
+==== Preparation (gem and source tarball only)
 If you want to install Phusion Passenger via the gem or the source tarball,
-then some preparation might be required. You can skip this subsection if
+then some preparations might be required. You can skip this subsection if
 you're installing Phusion Passenger via a native Linux package, because no
 compilation is necessary.
 
+===== Switching to a root command prompt =====
+
+Before installing, you will probably need to switch to the `root` user first.
+When you install Phusion Passenger via a gem or a source tarball, some Phusion
+Passenger files have to be compiled, which requires write access to the
+directory in which the Phusion Passenger files are located. On Unix systems,
+the root user is the user who has write access to the entire system. So unless
+you know that your normal user account has write access to the Phusion Passenger
+directory, you should switch to root before installing Phusion Passenger.
+
+You can switch to root by typing the following command:
+
+-------------------------
+sudo -s
+-------------------------
+
+This will open a command prompt as the root user, from which you can proceed
+with installing Phusion Passenger.
+
+If your system does not have 'sudo' installed, please type the following command instead, which should do the same thing:
+
+-------------------------
+su
+-------------------------
+
 [[specifying_correct_apache_install]]
 ===== Specifying the correct Apache installation =====
 
-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:
+The Phusion Passenger installer will attempt to automatically detect Apache,
+and compile Phusion Passenger against that Apache version. It does this by
+looking for the `apxs` or `apxs2` command in the PATH environment variable.
+Apxs is an integral part of any Apache installation.
+
+However, some systems have multiple Apache installations. This is likely
+the case on MacOS X: the OS ships with Apache, but users tend to install
+another Apache version seperately, e.g. via MacPorts. If your system has
+multiple Apache installations, then you will need to tell the Phusion Passenger
+installer which one to use. It is very important that you specify the
+correct Apache installation, because if you load Phusion Passenger in an
+Apache installation that it wasn't compiled against, then it will likely
+crash.
+
+On yet other systems, Apache is installed in a non-standard location,
+preventing the Phusion Passenger installer from detecting Apache. This
+is most likely the case on systems on which Apache was installed by hand
+from source, i.e. as opposed to installed through the system's native
+package manager. If this is the case, then you will also have to tell
+the installer where it can find Apache.
+
+To do so, set the `APXS2` environment variable to the full path of the
+correct `apxs` or `apxs2` command. Suppose that you want to use the Apache
+installation in '/opt/apache2'. Then, assuming that the corresponding
+`apxs` program's path is '/opt/apache2/bin/apxs', type:
+
 ----------------------------------
 export APXS2=/opt/apache2/bin/apxs
 ----------------------------------
@@ -101,6 +126,14 @@ 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.
 
+.Environment variables and 'sudo'
+NOTE: By default, the 'sudo' command will erase any environment variables that it
+doesn't recognize, prior to executing the given command. So if you set APXS2 as a
+normal user, then run `sudo passenger-install-apache2-module` (which is the command
+for the Phusion Passenger installer), then the installer will not receive the
+environment variable value that you set. To solve this problem, please become root
+prior to setting any environment variables, as described in the previous subsection.
+
 [[specifying_ruby_installation]]
 ===== Specifying the correct Ruby installation =====
 
@@ -169,6 +202,17 @@ sudo apt-get update
 sudo apt-get install libapache2-mod-passenger
 ------------------------------------------------------
 
+==== What does the installer do? ====
+
+Although we call it an ``installer'', it doesn't actually install anything.
+The installer checks whether all required dependencies are installed,
+compiles Phusion Passenger for you, and tells you how to modify the Apache
+configuration file, but it doesn't copy any files around.
+
+`passenger-install-apache2-module` is actually just a user-friendly frontend
+around the command `rake apache2`, which performs the actual compilation of
+Phusion Passenger.
+
 
 === Operating system-specific instructions and information ===
 
@@ -188,6 +232,105 @@ J Aaron Farr has written a link:http://cubiclemuses.com/cm/articles/2009/04/09/r
 about setting up Ruby on Rails and Phusion Passenger on OpenSolaris and EC2.
 
 
+=== Upgrading or downgrading Phusion Passenger ===
+
+==== Via a gem or a source tarball ====
+
+To ugrade or downgrade Phusion Passenger via the gem or the source tarball, install the newer
+or older version as you normally would; that is, install the gem or unpack the tarball, and
+run `passenger-install-apache2-module`. Eventually `passenger-install-apache2-module` will tell
+you to copy & paste some settings into the Apache configuration file; something that looks along
+the lines of:
+
+-----------------------------------
+LoadModule passenger_module ...
+PassengerRoot ...
+PassengerRuby ...
+-----------------------------------
+
+Because you already have Phusion Passenger installed, you already have the same settings
+in your Apache configuration file, just with different values. Replace the old settings with
+the new ones that the installer outputs.
+
+When you're done, restart Apache.
+
+==== Via a native Linux package
+
+There are no special instructions required to upgrade or downgrade Phusion Passenger
+via a native Linux package.
+
+=== Unloading (disabling) Phusion Passenger from Apache without uninstalling it ===
+
+You can temporarily unload (disable) Phusion Passenger from Apache, without
+uninstalling the Phusion Passenger files, so that Apache behaves as if Phusion
+Passenger was never installed in the first place. This might be useful to you if,
+for example, you seem to be experiencing a problem caused by Phusion Passenger,
+but you want to make sure whether that's actually the case, without having
+to through the hassle of uninstalling Phusion Passenger completely.
+
+To unload Phusion Passenger from Apache, edit your Apache configuration file(s)
+and comment out:
+
+- all Phusion Passenger configuration directives.
+- the 'LoadModule passenger_module' directive.
+
+For example, if your configuration file looks like this...
+
+-----------------------------------
+Listen *:80
+NameVirtualHosts *:80
+....
+
+LoadModule passenger_module /somewhere/passenger-x.x.x/ext/apache2/mod_passenger.so
+
+PassengerRuby /usr/bin/ruby
+PassengerRoot /somewhere/passenger/x.x.x
+PassengerMaxPoolSize 10
+
+<VirtualHost *:80>
+    ServerName www.foo.com
+    DocumentRoot /webapps/foo/public
+    RailsBaseURI /rails
+</VirtualHost>
+-----------------------------------
+
+...then comment out the relevant directives, so that it looks like this:
+
+-----------------------------------
+Listen *:80
+NameVirtualHosts *:80
+....
+
+# LoadModule passenger_module /somewhere/passenger-x.x.x/ext/apache2/mod_passenger.so
+
+# PassengerRuby /usr/bin/ruby
+# PassengerRoot /somewhere/passenger/x.x.x
+# PassengerMaxPoolSize 10
+
+<VirtualHost *:80>
+    ServerName www.foo.com
+    DocumentRoot /webapps/foo/public
+    # RailsBaseURI /rails
+</VirtualHost>
+-----------------------------------
+
+After you've done this, save the file and restart Apache.
+
+=== Uninstalling Phusion Passenger ===
+
+To uninstall Phusion Passenger, please first remove all Phusion Passenger
+configuration directives from your Apache configuration file(s). After you've
+done this, you need to remove the Phusion Passenger files.
+
+- If you installed Phusion Passenger via a gem, then type `gem uninstall passenger`.
+  You might have to run this as root.
+- If you installed Phusion Passenger via a source tarball, then remove the directory
+  in which you placed the extracted Phusion Passenger files. This directory is the
+  same as the one pointed to the by 'PassengerRoot' configuration directive.
+- If you installed Phusion Passenger via a Debian package, then remove type
+  `sudo apt-get remove libapache2-mod-passenger`.
+
+
 == Deploying a Ruby on Rails application ==
 
 Suppose you have a Ruby on Rails application in '/webapps/mycook', and you own
@@ -274,7 +417,7 @@ 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 <<application_root,root folder>>. Phusion Passenger will
-   automatically restart the application.
+   automatically restart the application during the next request.
 
 For example, to restart our example MyCook application, we type this in the
 command line:
@@ -282,6 +425,11 @@ command line:
 touch /webapps/mycook/tmp/restart.txt
 -------------------------------------------
 
+Please note that, unlike earlier versions of Phusion Passenger, 'restart.txt'
+is not automatically deleted. Phusion Passenger checks whether the timestamp
+of this file has changed in order to determine whether the application should
+be restarted.
+
 === Migrations ===
 
 Phusion Passenger is not related to Ruby on Rails migrations in any way. To
@@ -347,7 +495,7 @@ $ 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>"]
+    [200, { "Content-Type" => "text/html" }, ["hello <b>world</b>"]]
 end
 run app
 -------------------------------------------
@@ -631,10 +779,10 @@ follows:
 <VirtualHost *:80>
     ServerName www.foo.com
     DocumentRoot /apps/foo/public
-    <Location /wordpress>
+    <Directory /apps/foo/public/wordpress>
         PassengerEnabled off
         AllowOverride all      # <-- Makes Wordpress's .htaccess file work.
-    </Location>
+    </Directory>
 </VirtualHost>
 ------------------------------------
 
@@ -649,10 +797,11 @@ This way, Phusion Passenger will not interfere with Wordpress.
 
 In each place, it may be specified at most once. The default value is 'on'.
 
+[[PassengerTempDir]]
 === 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.
+files. This includes things such as Unix socket files, buffered file uploads
+(see also <<PassengerUploadBufferDir,PassengerUploadBufferDir>>), etc.
 
 This option may be specified once, in the global server configuration. The
 default temp directory that Phusion Passenger uses is '/tmp'.
@@ -678,6 +827,36 @@ sudo -E passenger-status
 # The -E option tells 'sudo' to preserve environment variables.
 ----------------------------------------------------------
 
+[[PassengerUploadBufferDir]]
+=== PassengerUploadBufferDir <directory> ===
+Phusion Passenger buffers large file uploads to disk in order prevent slow file
+uploads from blocking web applications. By default, a subdirectory in the
+system's temporary files directory (or a subdirectory in the directory specified
+in <<PassengerTempDir,PassengerTempDir>>, if set) is automatically created for
+storing these buffered file uploads.
+
+This configuration directive allows you to specify a different directory for storing
+buffered file uploads. If you've specified such a directory (as opposed to using
+Phusion Passenger's default) then you *must* ensure that this directory exists.
+
+This configuration directive is also useful if you're using apache2-mpm-itk.
+The buffered file upload directory that Phusion Passenger creates by default has
+very strict permissions: it can only be accessed by the Apache worker processes.
+However, Phusion Passenger assumes that all Apache worker processes are running
+as the same user. apache2-mpm-itk breaks this assumption by running multiple
+Apache worker processes as different users. So if you're using apace2-mpm-itk,
+you should set this option to a directory that is writable by all Apache worker
+processes, such as '/tmp'.
+
+You may specify 'PassengerUploadBufferDir' 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.
+
 === PassengerRestartDir <directory> ===
 As described in the deployment chapters of this document, Phusion Passenger
 checks the file 'tmp/restart.txt' in the applications'
@@ -1419,6 +1598,94 @@ try drogus's link:http://github.com/drogus/apache-upload-progress-module/tree/ma
 Apache upload progress module] instead.
 
 
+== Under the hood ==
+Phusion Passenger hides a lot of complexity for the end user (i.e. the web server
+system administrator), but sometimes it is desirable to know what is going on.
+This section describes a few things that Phusion Passenger does under the hood.
+
+=== Static assets serving ===
+Phusion Passenger accelerates serving of static files. This means that, if an URI
+maps to a file that exists, then Phusion Passenger will let Apache serve that file
+directly, without hitting the web application.
+
+Phusion Passenger does all this without the need for any mod_rewrite rules. People
+who are switching from an old Mongrel-based setup might have mod_rewrite rules such
+as these:
+
+------------------------------------------------------------
+# Check whether this request has a corresponding file; if that
+# exists, let Apache serve it, otherwise forward the request to
+# Mongrel.
+RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
+RewriteRule ^(.*)$ balancer://mongrel%{REQUEST_URI} [P,QSA,L]
+------------------------------------------------------------
+
+These kind of mod_rewrite rules are no longer required, and you can safely remove
+them.
+
+=== Page caching support ===
+For each HTTP request, Phusion Passenger will automatically look for a corresponding
+page cache file, and serve that if it exists. It does this by appending ".html" to
+the filename that the URI normally maps to, and checking whether that file exists.
+This check occurs after checking whether the original mapped filename exists (as part
+of static asset serving). All this is done without the need for special mod_rewrite
+rules.
+
+For example, suppose that the browser requests '/foo/bar'.
+
+1. Phusion Passenger will first check whether this URI maps to a static file, i.e.
+   whether the file 'foo/bar' exists in the web application's 'public' directory.
+   If it does then Phusion Passenger will serve this file through Apache immediately.
+2. If that doesn't exist, then Phusion Passenger will check whether the file
+   'foo/bar.html' exists. If it does then Phusion Passenger will serve this file
+   through Apache immediately.
+3. If 'foo/bar.html' doesn't exist either, then Phusion Passenger will forward the
+   request to the underlying web application.
+
+Note that Phusion Passenger's page caching support doesn't work if your web
+application uses a non-standard page cache directory, i.e. if it doesn't cache to
+the 'public' directory. In that case you'll need to use mod_rewrite to serve such
+page cache files.
+
+=== How Phusion Passenger detects whether a virtual host is a web application ===
+After you've read the deployment instructions you might wonder how Phusion Passenger
+knows that the DocumentRoot points to a web application that Phusion Passenger is
+able to serve, and how it knows what kind of web application it is (e.g. Rails or Rack).
+
+Phusion Passenger checks whether the virtual host is a Rails application by checking
+whether the following file exists:
+
+------------------------------------------------
+dirname(DocumentRoot) + "/config/environment.rb"
+------------------------------------------------
+
+If you're not a programmer and don't understand the above pseudo-code snippet, it means
+that Phusion Passenger will:
+
+1. Extract the parent directory filename from the value of the DocumentRoot directory.
+2. Append the text "/config/environment.rb" to the result, and check whether the resulting
+   filename exists.
+
+So suppose that your document root is '/webapps/foo/public'. Phusion Passenger will check
+whether the file '/webapps/foo/config/environment.rb' exists.
+
+Note that Phusion Passenger does *not* resolve any symlinks in the document root path since
+version 2.2.0 -- in contrast to versions earlier than 2.2.0, which does resolve symlinks.
+So for example, suppose that your DocumentRoot points to '/home/www/example.com', which in
+turn is a symlink to '/webapps/example.com/public'. In versions earlier than 2.2.0, Phusion
+Passenger will check whether '/webapps/example.com/config/environment.rb' exists because it
+resolves all symlinks. Phusion Passenger 2.2.0 and later however will check for
+'/home/www/config/environment.rb'. This file of course doesn't exist, and as a result Phusion
+Passenger will not activate itself for this virtual host, and you'll most likely see an Apache
+mod_dirindex directory listing.
+
+If you're running into this problem, you can explicitly tell Phusion Passenger what the
+correct application root is through the <<PassengerAppRoot,PassengerAppRoot>> configuration directive.
+
+Autodetection of Rack applications happens through the same mechanism, exception that
+Phusion Passenger will look for 'config.ru' instead of 'config/environment.rb'.
+
+
 include::users_guide_snippets/appendix_a_about.txt[]
 
 include::users_guide_snippets/appendix_b_terminology.txt[]