[[user_switching]]
=== User switching (security) ===

There is a problem that plagues most PHP web hosts, namely the fact that all PHP
applications are run in the same user context as the web server. So for
example, Joe's PHP application will be able to read Jane's PHP application's
passwords. This is obviously undesirable on many servers.

Phusion Passenger solves this problem by implementing 'user switching'. A Rails
application is started as the owner of the file 'config/environment.rb',
and a Rack application is started as the owner of the file 'config.ru'.
So if '/home/webapps/foo/config/environment.rb' is owned by 'joe', then Phusion
Passenger will launch the corresponding Rails application as 'joe' as well.

This behavior is the default, and you don't need to configure anything. But
there are things that you should keep in mind:

- The owner of 'environment.rb'/'config.ru' must have read access to the application's
  root directory, and read/write access to the application's 'logs' directory.
- This feature is only available if Apache is started by 'root'. This is the
  case on most Apache installations.
- Under no circumstances will applications be run as 'root'. If
  'environment.rb'/'config.ru' is owned as root or by an unknown user, then the
  Rails/Rack application will run as the user specified by
ifdef::apache[]
  <<PassengerDefaultUser,PassengerDefaultUser>> and
  <<PassengerDefaultGroup,PassengerDefaultGroup>>.
endif::[]
ifdef::nginx[]
  <<PassengerDefaultUser,passenger_default_user>> and
  <<PassengerDefaultGroup,passenger_default_group>>.
endif::[]

User switching can be disabled with the
ifdef::apache[<<PassengerUserSwitching,PassengerUserSwitching>>]
ifdef::nginx[<<PassengerUserSwitching,passenger_user_switching>>]
option.


[[reducing_memory_usage]]
=== Reducing memory consumption of Ruby on Rails applications by 33% ===

Is it possible to reduce memory consumption of your Rails applications by 33% on average,
by using http://www.rubyenterpriseedition.com/[Ruby Enterprise Edition].
Please visit the website for details.

Note that this feature does not apply to Rack applications.

[[capistrano]]
=== Capistrano recipe ===

Phusion Passenger can be combined with link:http://capify.org/[Capistrano].
The following Capistrano recipe demonstrates Phusion Passenger support.
It assumes that you're using Git as version control system.

--------------------------------------------------
set :application, "myapp"
set :domain,      "example.com"
set :repository,  "ssh://#{domain}/path-to-your-git-repo/#{application}.git"
set :use_sudo,    false
set :deploy_to,   "/path-to-your-web-app-directory/#{application}"
set :scm,         "git"

role :app, domain
role :web, domain
role :db,  domain, :primary => true

namespace :deploy do
  task :start, :roles => :app do
    run "touch #{current_release}/tmp/restart.txt"
  end
  
  task :stop, :roles => :app do
    # Do nothing.
  end
  
  desc "Restart Application"
  task :restart, :roles => :app do
    run "touch #{current_release}/tmp/restart.txt"
  end
end
--------------------------------------------------


[[bundler_support]]
=== Bundler support ===

Phusion Passenger has automatic support for link:http://gembundler.com/git.html[Bundler].
It works as follows:

- If you have a '.bundle/environment.rb' in your application root, then Phusion
  Passenger will require that file before loading your application.
- Otherwise, if you have a 'Gemfile', then Phusion Passenger will automatically call
  `Bundler.setup()` before loading your application.

It's possible that your application also calls `Bundler.setup` during loading, e.g. in
'config.ru' or in 'config/boot.rb'. This is the case with Rails 3, and is also the case if you
modified your 'config/boot.rb' according to the
link:http://gembundler.com/rails23.html[Bundler Rails 2.3 instructions].
This leads to `Bundler.setup` being called twice, once before the application startup file
is required and once during application startup. However this is harmless and doesn't
have any negative effects.

Phusion Passenger assumes that you're using Bundler >= 0.9.5. If you don't want Phusion
Passenger to run its Bundler support code, e.g. because you need to use an older version
of Bundler with an incompatible API or because you use a system other than Bundler, then
you can override Phusion Passenger's Bundler support code by creating a file
'config/setup_load_paths.rb'. If this file exists then it will be required before loading
the application startup file. In this file you can do whatever you need to setup Bundler
or a similar system.


[[moving_phusion_passenger]]
=== Moving Phusion Passenger to a different directory ===

It is possible to relocate the Phusion Passenger files to a different directory. It
involves two steps:

1. Moving the directory.
2. Updating the ``PassengerRoot'' configuration option in Apache.

For example, if Phusion Passenger is located in '/opt/passenger/', and you'd like to
move it to '/usr/local/passenger/', then do this:

1. Run the following command:
+
------------------------------------
mv /opt/passenger /usr/local/passenger
------------------------------------
2. Edit your Apache configuration file, and set:
+
------------------------------------
PassengerRoot /usr/local/passenger
------------------------------------

=== Installing multiple Ruby on Rails versions ===

Each Ruby on Rails applications that are going to be deployed may require a
specific Ruby on Rails version. You can install a specific version with
this command:
-----------------------------
gem install rails -v X.X.X
-----------------------------
where 'X.X.X' is the version number of Ruby on Rails.

All of these versions will exist in parallel, and will not conflict with each
other. Phusion Passenger will automatically make use of the correct version.

=== 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.

[[sub_uri_deployment_uri_fix]]
=== How to fix broken images/CSS/JavaScript URIs in sub-URI deployments

Some people experience broken images and other broken static assets when they
deploy their application to a sub-URI (i.e. 'http://mysite.com/railsapp/').
The reason for this usually is that you used a
static URI for your image in the views. This means your 'img' source probably refers
to something like '/images/foo.jpg'. The leading slash means that it's an absolute URI:
you're telling the browser to always load 'http://mysite.com/images/foo.jpg' no
matter what. The problem is that the image is actually at
'http://mysite.com/railsapp/images/foo.jpg'. There are two ways to fix this.

The first way (not recommended) is to change your view templates to refer to
'images/foo.jpg'. This is a relative URI: note the lack of a leading slash). What
this does is making the path relative to the current URI. The problem is that if you
use restful URIs, then your images will probably break again when you add a level to
the URI.
For example, when you're at 'http://mysite.com/railsapp' the browser will look for
'http://mysite.com/railsapp/images/foo.jpg'. But when you're at
'http://mysite.com/railsapp/controller'. the browser will look for
'http://mysite.com/railsapp/controller/images/foo.jpg'.
So relative URIs usually don't work well with layout templates.

The second and highly recommended way is to always use Rails helper methods to
output tags for static assets. These helper methods automatically take care
of prepending the base URI that you've deployed the application to. For images
there is `image_tag`, for JavaScript there is `javascript_include_tag` and for
CSS there is `stylesheet_link_tag`. In the above example you would simply remove
the '<img>' HTML tag and replace it with inline Ruby like this:

---------------------------------------
<%= image_tag("foo.jpg") %>
---------------------------------------

This will generate the proper image tag to `$RAILS_ROOT/public/images/foo.jpg`
so that your images will always work no matter what sub-URI you've deployed to.

These helper methods are more valuable than you may think. For example they also
append a timestamp to the URI to better facilitate HTTP caching. For more information,
please refer to
link:http://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html[the Rails API docs].