1. By installing the Phusion Passenger gem, as instructed on the “Install” page on the Phusion Passenger website.
2. By downloading the source tarball from the Phusion Passenger website (passenger-x.x.x.tar.gz).
3. By installing a native Linux package (e.g. Debian package).

Switching to a root command prompt

sudo -s

su

Specifying the correct Apache installation

export APXS2=/opt/apache2/bin/apxs

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 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 the correct Ruby installation

export PATH=/opt/myruby/bin:$PATH

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>

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>

<VirtualHost *:80>
    ServerName www.mycook.com
    DocumentRoot /webapps/mycook/public
    <Directory /webapps/mycook/public>
        Allow from all
        Options -MultiViews
    </Directory>
</VirtualHost>

<VirtualHost *:80>
    ServerName www.phusion.nl
    DocumentRoot /websites/phusion
    <Directory /websites/phusion>
        Allow from all
    </Directory>
</VirtualHost>

ln -s /webapps/mycook/public /websites/phusion/rails

<VirtualHost *:80>
    ServerName www.phusion.nl
    DocumentRoot /websites/phusion
    <Directory /websites/phusion>
        Allow from all
    </Directory>

    RailsBaseURI /rails                   # <-- These lines have
    <Directory /websites/phusion/rails>   # <-- been added.
        Options -MultiViews               # <--
    </Directory>                          # <--
</VirtualHost>

touch /webapps/mycook/tmp/restart.txt

$ mkdir /webapps/rack_example
$ mkdir /webapps/rack_example/public
$ mkdir /webapps/rack_example/tmp

$ cd /webapps/rack_example
$ some_awesome_editor config.ru
...type in some source code...
$ cat config.ru
app = proc do |env|
    [200, { "Content-Type" => "text/html" }, ["hello <b>world</b>"]]
end
run app

<VirtualHost *:80>
    ServerName www.rackexample.com
    DocumentRoot /webapps/rack_example/public
    <Directory /webapps/rack_example/public>
        Allow from all
        Options -MultiViews
    </Directory>
</VirtualHost>

<VirtualHost *:80>
    ServerName www.rackapp.com
    DocumentRoot /webapps/rackapp/public
    <Directory /webapps/rackapp/public>
        Allow from all
        Options -MultiViews
    </Directory>
</VirtualHost>

<VirtualHost *:80>
    ServerName www.phusion.nl
    DocumentRoot /websites/phusion
    <Directory /websites/phusion>
        Allow from all
    </Directory>
</VirtualHost>

ln -s /webapps/rackapp/public /websites/phusion/rack

<VirtualHost *:80>
    ServerName www.phusion.nl
    DocumentRoot /websites/phusion
    <Directory /websites/phusion>
        Allow from all
    </Directory>

    RackBaseURI /rails                    # <-- These lines have
    <Directory /websites/phusion/rails>   # <-- been added.
        Options -MultiViews               # <--
    </Directory>                          # <--
</VirtualHost>

touch /webapps/rackapp/tmp/restart.txt

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

Backend process A:  [*     ]  (1 request in queue)
Backend process B:  [***   ]  (3 requests in queue)
Backend process C:  [***   ]  (3 requests in queue)
Backend process D:  [***   ]  (3 requests in queue)

Backend process A:  [*X    ]  (2 request in queue)
Backend process B:  [***   ]  (3 requests in queue)
Backend process C:  [***   ]  (3 requests in queue)
Backend process D:  [***   ]  (3 requests in queue)

Backend process A:  [*XY   ]  (3 requests in queue)
Backend process B:  [***   ]  (3 requests in queue)
Backend process C:  [***   ]  (3 requests in queue)
Backend process D:  [***   ]  (3 requests in queue)

<VirtualHost *:80>
    ServerName www.foo.com
    DocumentRoot /apps/foo/public
    <Directory /apps/foo/public/wordpress>
        PassengerEnabled off
        AllowOverride all      # <-- Makes Wordpress's .htaccess file work.
    </Directory>
</VirtualHost>

export PASSENGER_TMPDIR=/my_temp-dir
sudo -E passenger-status
# The -E option tells 'sudo' to preserve environment variables.

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

render :text => lambda { |response, output|
    10.times do |i|
        output.write("entry #{i}\n")
        output.flush
        sleep 1
    end
}

class Response
    def each
        10.times do |i|
            yield("entry #{i}\n")
            sleep 1
        end
    end
end

app = lambda do |env|
    [200, { "Content-Type" => "text/plain" }, Response.new]
end

• In the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.

• In the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.

• In the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.
• In .htaccess, if AllowOverride Options is on.

1. at least the given number of instances will be spawned.
2. the given number of processes will be kept around even when instances are being idle cleaned (see PassengerPoolIdleTime).

• 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 the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.
• In .htaccess, if AllowOverride Limits is on.

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

• In the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.
• In .htaccess, if AllowOverride Limits is on.

• This directive accepts the URL of the web application you want to pre-start, not a on/off value! This might seem a bit weird, but read on for rationale. As for the specifics of the URL:
  • The domain part of the URL must be equal to the value of the ServerName directive of the VirtualHost block that defines the web application.
  • Unless the web application is deployed on port 80, the URL should contain the web application’s port number too.
  • The path part of the URL must point to some URI that the web application handles.
• You will probably want to combine this option with PassengerMinInstances because application instances started with PassengerPreStart are subject to the usual idle timeout rules. See the example below for an explanation.

• In the global server configuration.
• In a virtual host configuration block.

Example 1: basic usage

<VirtualHost *:80>
   ServerName foo.com
   DocumentRoot /webapps/foo/public
</VirtualHost>

<VirtualHost *:3500>
   ServerName bar.com
   DocumentRoot /webapps/bar/public
</VirtualHost>

<VirtualHost *:80>
   ServerName foo.com
   DocumentRoot /webapps/foo/public
</VirtualHost>

<VirtualHost *:3500>
   ServerName bar.com
   DocumentRoot /webapps/bar/public
</VirtualHost>

PassengerPreStart http://foo.com/           # <--- added
PassengerPreStart http://bar.com:3500/      # <--- added

Example 2: pre-starting apps that are deployed in sub-URIs

<VirtualHost *:80>
   ServerName myblog.com
   DocumentRoot /webapps/wordpress
   RailsBaseURI /store
</VirtualHost>

<VirtualHost *:80>
   ServerName myblog.com
   DocumentRoot /webapps/wordpress
   RailsBaseURI /store
</VirtualHost>

PassengerPreStart http://myblog.com/store    # <----- added

PassengerPreStart http://myblog.com/    # <----- WRONG! Missing "/store" part.

Example 3: combining with PassengerMinInstances

<VirtualHost *:80>
   ServerName foo.com
   DocumentRoot /webapps/foo/public
   PassengerMinInstances 1      # <--- added
</VirtualHost>

<VirtualHost *:3500>
   ServerName bar.com
   DocumentRoot /webapps/bar/public
   PassengerMinInstances 1      # <--- added
</VirtualHost>

PassengerPreStart http://foo.com/
PassengerPreStart http://bar.com:3500/

So why a URL? Why not just an on/off flag?

What does Phusion Passenger do with the URL?

HEAD / HTTP/1.1
Host: bar.com
Connection: close

HEAD /store HTTP/1.1
Host: myblog.com
Connection: close

Do I need to edit /etc/hosts and point the domain in the URL to 127.0.0.1?

My web application consists of multiple web servers. What URL do I need to specify, and in which web server’s Apache config file?

Does PassengerPreStart support https:// URLs?

• In the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.
• In .htaccess.

• 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 the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.
• In .htaccess, if AllowOverride Options is on.

• 0: Show only errors and warnings.
• 1: Show the most important debugging information. This might be useful for system administrators who are trying to figure out the cause of a problem.
• 2: Show more debugging information. This is typically only useful for developers.
• 3: Show even more debugging information.

• 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 the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.
• In .htaccess, if AllowOverride Options is on.

• In the global server configuration.
• In a virtual host configuration block.

• In the global server configuration.
• In a virtual host configuration block.

• 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 the global server configuration.
• In a virtual host configuration block.
• In a <Directory> or <Location> block.
• In .htaccess, if AllowOverride Options is on.

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.

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.

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.

1. Your Apache configuration is too strict, and does not allow HTTP clients to access static assets. This can be achieved with an Allow from all directive in the correct place. For example:

   <Directory "/webapps/mycook/public">
      Options FollowSymLinks
      AllowOverride None
      Order allow,deny
      Allow from all
   </Directory>

   See also this discussion.
2. The Apache process doesn’t have permission to access your Rails application’s folder. Please make sure that the Rails application’s folder, as well as all of its parent folders, have the correct permissions and/or ownerships.

• If you’ve installed Phusion Passenger via a gem, then run this command to determine Phusion Passenger’s root folder:

  passenger-config --root

  Next, run the following command:

  chcon -R -h -t httpd_sys_content_t /path-to-passenger-root

  where /path-to-passenger-root should be replaced with whatever passenger-config –root printed.
• If you’ve installed Phusion Passenger via the source tarball, then run the following command:

  chcon -R -h -t httpd_sys_content_t /path/to/passenger/folder

• By default, Phusion Passenger runs Rails applications in production mode, so please be sure to check production.log instead of development.log. See RailsEnv for configuration.
• By default, Phusion Passenger runs Rails applications as the owner of environment.rb. So the log file can only be written to if that user has write permission to the log file. Please chmod or chown your log file accordingly.
  See User switching (security) for details.

[bash@localhost root]# passenger-memory-stats
------------- Apache processes --------------.
PID    PPID  Threads  VMSize   Private  Name
---------------------------------------------.
5947   1     9        90.6 MB  0.5 MB   /usr/sbin/apache2 -k start
5948   5947  1        18.9 MB  0.7 MB   /usr/sbin/fcgi-pm -k start
6029   5947  1        42.7 MB  0.5 MB   /usr/sbin/apache2 -k start
6030   5947  1        42.7 MB  0.5 MB   /usr/sbin/apache2 -k start
6031   5947  1        42.5 MB  0.3 MB   /usr/sbin/apache2 -k start
6033   5947  1        42.5 MB  0.4 MB   /usr/sbin/apache2 -k start
6034   5947  1        50.5 MB  0.4 MB   /usr/sbin/apache2 -k start
23482  5947  1        82.6 MB  0.4 MB   /usr/sbin/apache2 -k start
### Processes: 8
### Total private dirty RSS: 3.50 MB

--------- Passenger processes ---------.
PID    Threads  VMSize   Private  Name
---------------------------------------.
6026   1        10.9 MB  4.7 MB   Passenger spawn server
23481  1        26.7 MB  3.0 MB   Passenger FrameworkSpawner: 2.0.2
23791  1        26.8 MB  2.9 MB   Passenger ApplicationSpawner: /var/www/projects/app1-foobar
23793  1        26.9 MB  17.1 MB  Rails: /var/www/projects/app1-foobar
### Processes: 4
### Total private dirty RSS: 27.76 M

[bash@localhost root]# passenger-status
----------- General information -----------
max      = 6
count    = 1
active   = 0
inactive = 1

----------- Domains -----------
/var/www/projects/app1-foobar:
  PID: 9617      Sessions: 0    Processed: 7       Uptime: 2m 23s

  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

  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"

bash# passenger-status --verbose
----------- General information -----------
max      = 6
count    = 2
active   = 0
inactive = 2
Waiting on global queue: 0

----------- Application groups -----------
/Users/hongli/Sites/rack.test:
  App root: /Users/hongli/Sites/rack.test
  * PID: 24235   Sessions: 0    Processed: 7       Uptime: 17s
      URL     : http://127.0.0.1:58122
      Password: nFfVOX1F8LjZ90HJh28Sd_htJOsgRsNne2QXKf8NIXw
  * PID: 24250   Sessions: 0    Processed: 4       Uptime: 1s
      URL     : http://127.0.0.1:57933
      Password: _RGXlQ9EGDGJKLevQ_qflUtF1KmxEo2UiRzMwIE1sBY

bash# curl -H "X-Passenger-Connect-Password: nFfVOX1F8LjZ90HJh28Sd_htJOsgRsNne2QXKf8NIXw" http://127.0.0.1:58122/

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

gem install rails -v X.X.X

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

# 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]

dirname(DocumentRoot) + "/config/environment.rb"

/apps/foo/       <------ This is the Rails application's application root!
   |
   +- app/
   |   |
   |   +- controllers/
   |   |
   |   +- models/
   |   |
   |   +- views/
   |
   +- config/
   |   |
   |   +- environment.rb
   |   |
   |   +- ...
   |
   +- public/
   |   |
   |   +- ...
   |
   +- ...

/apps/bar/      <----- This is the Rack application's application root!
   |
   +- public/
   |    |
   |    +- ...
   |
   +- config.ru
   |
   +- ...

/apps/baz/      <----- This is the WSGI application's application root!
   |
   +- public/
   |    |
   |    +- ...
   |
   +- passenger_wsgi.py
   |
   +- ...

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

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

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

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