====== Using Phusion Passenger (a.k.a. mod_rails) ======

The latest version of the Brightbox Gem (v2.2) supports using Phusion Passenger instead of the standard mongrel configuration. Currently we only support this configuration if you are using Ubuntu 8.04 Hardy, and is not available if you are on an Ubuntu Dapper install. You can upgrade to Hardy by ordering a new box, moving your data and then cancelling the old box.

We have apt packages available for Ruby Enterprise Edition and there is more information on setting your Brightbox up to use Ruby Enterprise Edition with Passenger over on the [[ docs:ruby-enterprise | Ruby Enterprise Packages ]] page.

==== Configuring a fresh deployment to use passenger ====

A new option has been added to the Brightbox gem, you now need to supply an option specifying either "mongrel" or "passenger" depending on your preference.

<code>
  brightbox -i example-001.vm.brightbox.net -a passenger .
</code>

This will create the file ''config/deploy.rb'' containing the details needed to deploy your application. Edit this file and change the settings as required.


==== Passenger Deployment options ====

<code>
set :passenger_restart_strategy, :hard
</code>

By default, restarting passenger requires creating a file called "restart.txt" which signals the application to gracefully restart. The old passenger processes then time out after 10 minutes of inactivity. Unfortunately this results in stale database connections using up your Brightbox MySQL connection allowance so by default we perform a more immediate "kill" of the passenger processes before starting new ones. Should you have enough database connections or experience problems with the default you can change the above option to :soft to restart in the normal manner.
==== Controlling the number of Passenger processes ====

Passenger, by default, is configured to spawn up to six ruby processes to handle incoming requests.  If you are using Ruby on Rails, each ruby process can be between 50 and 100Mb in size - and this can cause Out of Memory errors on smaller boxes.  These manifest as 500 errors, "broken pipe" messages or, in the worst cases, Apache or the ssh daemon shutting down (requiring a reboot).  

In order to limit the number of processes that Passenger creates, there are two directives that can be applied.  We normally create an extra configuration file in ''/etc/apache2/conf.d/passenger.conf'' (this needs to be created as root) with the following contents: 

<code>
PassengerMaxPoolSize 4
PassengerMaxInstancesPerApp 2
PassengerPoolIdleTime 300
</code>

(Phusion recommend that PassengerMaxPoolSize should be no more than 2 for a 256Mb box, although the actual memory usage of your application will govern the optimum value)

You will then need to reload Apache to tell it to pick up the new settings.  

The configuration above means that Passenger will create up to two ruby processes for each application on that box, with no more than four ruby processes in action at any one time.  If a ruby process is left idle for more than 300 seconds it will be killed, releasing its memory.  
  

==== Converting from mongrel to passenger ====

There is no automated way to move from mongrel to passenger at this time, instead you will have to follow the steps below to setup your existing application to use passenger. This process will cause some downtime for you application while things are swapped over.

== On your Brightbox ==
  - Ensure you are running Ubuntu Hardy 8.04 (''cat /etc/lsb-release'')
  - Issue the command ''sudo monit -g <yourapp> stop all''
  - Delete the ''/etc/monit/conf.d/rails-<yourapp>.monitrc'' file
  - Issue the command ''sudo monit reload''


== On your development machine ==
  - Copy your deploy.rb over to a backup ''cp config/deploy.rb config/deploy.rb.old''
  - Re-run the ''brightbox'' command as detailed for a new customer using passenger
  - Copy any custom command from your deploy.rb.old over to your new deploy file
  - Run ''cap deploy:initial'' to run the installation procedure from scratch
  - Your Brightbox should now be setup to run your application using passenger