passenger 1.0.1

data/doc/Users guide.txt

@@ -0,0 +1,707 @@
+= Passenger users guide =
+
+image:images/phusion_banner.png[link="http://www.phusion.nl/"]
+
+Passenger is an Apache module, which makes deploying 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.
+
+This users guide will teach you:
+
+- How to install Passenger.
+- How to configure Passenger.
+- How to deploy a Ruby on Rails application.
+- How to solve common problems.
+
+This guide assumes that the reader is somewhat familiar with Apache and with
+using the commandline.
+
+
+== Installation ==
+
+=== Supported operating systems ===
+
+Passenger works on any POSIX-compliant operating system. In other words:
+practically any operating system on earth, except Microsoft Windows.
+
+Passenger has been tested on:
+
+- Ubuntu Linux 6.06 (x86)
+- Ubuntu Linux 7.10 (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 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.
+
+[[install_passenger]]
+=== Overview of download and installation methods ===
+
+There are two ways to install Passenger:
+
+1. By installing the Passenger gem, as instructed on the ``Install'' page
+   on the Passenger website.
+2. By downloading the source tarball from the Passenger website
+   ('passenger-x.x.x.tar.gz').
+
+In our opinion, installing the gem is easiest.
+
+Passenger provides an easy-to-use installer for installing the Passenger
+Apache module ('mod_passenger').
+
+NOTE: 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 ===
+
+If your system has multiple Apache installations (this is likely the case on
+MacOS X), then you will need to tell the 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 Passenger will automatically detect it.
+
+Every Apache installation has its own `apxs` program. You will need to tell
+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 ===
+
+If your system has multiple Ruby installations (this is likely the case on
+MacOS X), then you will need to tell the 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 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 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 the source tarball ===
+
+Extract the tarball to whatever location you prefer. The Passenger files
+are to reside in that location permanently. For example, if you would like
+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.
+
+
+== 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 in 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_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` 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.
+
+=== 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. 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
+-------------------------------------------
+
+
+== Configuring Passenger ==
+
+After installation, Passenger does not need any further configurations.
+Nevertheless, the system administrator may be interested in changing
+Passenger's behavior. Passenger's Apache module supports the following
+configuration options:
+
+RailsSpawnServer <filename>::
+	The location to the Passenger spawn server. This configuration option is
+	essential to Passenger. The correct value is given by the installer,
+	and should usually not be changed manually.
++
+This option may only occur once, in the global server configuration. If
+this option is not given, then Passenger will look for the program
+`passenger-spawn-server` in `$PATH`.
+
+RailsBaseURI <uri>::
+	Used to specify that the given URI is a Rails application. See
+	<<deploying_to_sub_uri,Deploying to a sub URI>> for an example.
++
+This option may occur multiple times, in the global server configuration or in a
+virtual host configuration block.
+
+RailsAutoDetect <on|off>::
+	Whether 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` configuration option:
++
+-----------------------------
+RailsAutoDetect off
+<VirtualHost *:80>
+    ServerName www.mycook.com
+    DocumentRoot /webapps/mycook/public
+    RailsBaseURI /
+</VirtualHost>
+-----------------------------
+
+[[RailsAllowModRewrite]]
+RailsAllowModRewrite <on|off>::
+	If enabled, Passenger will not override mod_rewrite rules. Please read
+	<<conflicting_apache_modules,Conflicting Apache modules>> for details.
++
+This option may occur in the global server configuration or in a virtual host
+configuration block. The default value is 'off'.
+
+RailsRuby <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'.
+
+[[rails_env]]
+RailsEnv <string>::
+	This option allows one to specify the default `RAILS_ENV` value.
++
+This option may only occur once, in the global server configuration.
+The default is 'production'.
++
+TIP: Even though it is not possible to specify a different RailsEnv
+per virtual host in the Apache configuration file, one can set the
+Rails environment by editing `RAILS_ENV=...` in the application's
+'config/environment.rb'.
+
+RailsMaxPoolSize <integer>::
+	The maximum number of Ruby on Rails 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 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 '20'.
++
+TIP: We strongly recommend you to <<reducing_memory_usage,use Ruby Enterprise
+Edition>>. This allows you to reduce your memory usage by about 33%. And it's
+not hard to install.
+
+RailsPoolIdleTime <integer>::
+	The maximum number of seconds that a Ruby on Rails application instance
+	may be idle. That is, if an application instance hasn't done anything after
+	the given number of seconds, then it will be shutdown in order to conserve
+	memory.
++
+Decreasing this value means that Rails 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 site. However, it will also
+free up resources used by Rails applications more quickly.
++
+The optimal value depends on the average time that a visitor spends on a single
+Rails 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 web page. But your
+mileage may vary.
++
+This option may only occur once, in the global server configuration.
+The default value is '120'.
+
+[[RailsUserSwitching]]
+RailsUserSwitching <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'.
+
+[[RailsDefaultUser]]
+RailsDefaultUser <username>::
+	Passenger enables <<user_switching,user switching support>> by default.
+	This configuration option allows one to specify which user Rails
+	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'.
+
+
+== Troubleshooting ==
+
+=== Problems during installation ===
+
+[[installing_ruby_dev]]
+==== Ruby development headers aren't installed ====
+
+.Symptoms
+*******************************************************************************
+Installing Passenger fails because of one of the following errors:
+
+- The 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.
+*******************************************************************************
+
+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 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 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 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.
+
+
+==== Passenger is using the wrong Apache during installation ====
+
+Please <<specifying_correct_apache_install,Specifying the correct Apache
+installation>>, and re-run the Passenger installer.
+
+
+==== Passenger is using the wrong Ruby during installation ====
+
+Please <<specifying_ruby_installation,Specifying the correct Ruby
+installation>>, and re-run the 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.
+=====================================================
+
+==== 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 Passenger>>.
+
+==== 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 RailsSpawnServer 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 Passenger files and
+folders, so that Apache can access them.
+
+- If you've installed Passenger via a gem, then you must first find out the
+  location in which RubyGems stores gem files. Type the following command:
++
+------------------------------------------------------------------
+gem environment | grep 'INSTALLATION DIRECTORY'
+------------------------------------------------------------------
++
+It should show something along the lines of:
++
+------------------------------------------------------------------
+  - INSTALLATION DIRECTORY: /usr/lib/ruby/gems/1.8
+------------------------------------------------------------------
++
+The directory name that you see in the output is the RubyGems gem folder.
+Next, we'll fix the Passenger folder permissions as follows:
++
+------------------------------------------------------------------
+cd /usr/lib/ruby/gems/1.8     # Replace this with whatever your gem folder is.
+cd gems
+chcon -R -h -t httpd_sys_content_t passenger-*
+------------------------------------------------------------------
+- If you've installed 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.
+
+
+== Tips and notes ==
+
+[[user_switching]]
+=== User switching (security) ===
+
+There is a problem that plagues most PHP web host, 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.
+
+Passenger solves this problem by implementing 'user switching'. A Rails
+application is started as the owner of the file 'config/environment.rb'. So if
+'/home/webapps/foo/config/environment.rb' is owned by 'joe', then 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.
+- This feature is only available if Apache is started by 'root'. This is the
+  case on most Apache installations.
+- Under no circumstances will Rails applications be run as 'root'. If
+  'environment.rb' is owned as root or by an unknown user, then the Rails
+  application will run as the user specified by
+  <<RailsDefaultUser,RailsDefaultUser>>.
+
+User switching can be disabled with the
+<<RailsUserSwitching,RailsUserSwitching>> option.
+
+
+[[reducing_memory_usage]]
+=== Reducing memory consumption of Ruby on Rails apps by 33% ===
+
+Is it possible to reduce memory consumption of your Rails apps by 33% on average,
+by using http://www.rubyenterpriseedition.com/[Ruby Enterprise Edition].
+Please visit the website for details.
+
+=== Moving Passenger to a different directory ===
+
+It is possible to relocate the Passenger files to a different directory. It
+involves two steps:
+
+1. Moving the directory.
+2. Updating the ``RailsSpawnServer'' configuration option in Apache.
+
+For example, if 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:
++
+------------------------------------
+RailsSpawnServer /usr/local/passenger/bin/passenger-spawn-server
+------------------------------------
+
+=== 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. Passenger will automatically make use of the correct version.
+
+=== X-Sendfile support ===
+
+Passenger does not provide X-Sendfile support by itself. Please install
+link:http://tn123.ath.cx/mod_xsendfile/[mod_xsendfile] for X-Sendfile support.
+
+[[conflicting_apache_modules]]
+=== Conflicting Apache modules ===
+
+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, 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 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. Passenger supports page caching
+out-of-the-box, without mod_rewrite.
+
+It is not fully understood how mod_alias conflicts with 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.
+
+
+== 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/"]
+
+Passenger is brought to you by Phusion.
+
+image:images/phusion_banner.png[link="http://www.phusion.nl/"]
+