How to run your packaged Rails app with Passenger


When you package a Rails application on, by default you'll end up with init scripts to run your application with the web server you defined in your Procfile. This allows you to install the package on any server and get your application running very easily with my-app scale web=1.

However, if you're already using Passenger for your deployments, you might want to keep it that way, in which case you can still benefit from the ease of installation provided by packages, but serve your application using Passenger.

In the rest of this article, we're assuming that nginx and Passenger are already installed on your server, and that your application name is my-app. You can very easily adapt the following instructions for apache2 + Passenger.

Add a new file to your repository

Passenger will need to know which ruby you want to use to load the application. We could directly point to the ruby binary embedded with your package, however it would not load any of the environment variables that you defined, which would not allow the application to start properly. The easiest way to fix this is to create a new file that will delegate any arguments to the CLI that comes with every package, which will take care of all of this for you.

For instance, you could create a new file in packaging/ruby with the following content:

exec "/usr/bin/my-app" "run" "ruby" "$@"

Then give it the right permissions, commit to your repository and push:

chmod a+x packaging/ruby
git add packaging/ruby
git commit -m "Add packaging/ruby"
git push

Wait a few seconds until your new package is generated, then install it on your server with the usual instructions.

Update your nginx server configuration

We can now simply update the nginx configuration so that the passenger_ruby configuration option points to your application's ruby. A minimal nginx configuration would look like:

server {
    listen 80;
    root /opt/my-app/public;

    passenger_enabled on;
    passenger_ruby /opt/my-app/packaging/ruby;

Reload nginx:

service nginx reload

That's it! Passenger should now load and serve your application when you access

Bonus points: automatically migrate and restart your application after an update

Passenger provides a mechanism to restart your application by touching a specific file at tmp/restart.txt. We can choose to automate this process by adding a postinstall hook to our package, and we'll also automatically run the database migrations if a DATABASE_URL is properly set:

In your .pkgr.yml file add the following line:

after_install: packaging/hooks/

Now create a new file at packaging/hooks/ with the following content:

set -e

if my-app config:get DATABASE_URL ; then
    my-app run rake db:migrate

touch tmp/restart.txt

exit 0

Finally, add and commit these files to your repository and push to generate a new package:

git add .pkgr.yml packaging/hooks/postinstall
git commit -m "Automatically migrate and restart our app"
git push

Now, every time you install a new version of your package, migrations will be run and Passenger will restart your application.

Happy packaging!