📚 Table of Contents

🗝️ Key Terms & Concepts

🔍 What is Passenger?

Passenger (also known as Phusion Passenger) is an application server that makes it easy to deploy Ruby, Node.js, and Python web apps. It integrates directly with Apache (or Nginx), handling process management, scaling, and more.

✅ Why Use Passenger with Rails?

🚦 Puma vs Passenger: Comparison

👍 Pros & Cons: Passenger vs Puma

❓ Why Use Passenger Over Puma?

• Seamless Apache/Nginx integration (no reverse proxy config needed)
• Automatic process management and scaling
• Zero-downtime deploys out of the box
• Great for teams who want stability and less manual tuning
• Easy to monitor and debug with built-in tools
• Ideal for shared hosting and traditional web apps

🛠️ How to Install Passenger & Rails

Install on Ubuntu/Debian

# Install dependencies
sudo apt update
sudo apt install -y dirmngr gnupg apt-transport-https ca-certificates
sudo apt install -y curl

# Add Passenger APT repo
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 561F9B9CAC40B2F7
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger $(lsb_release -cs) main > /etc/apt/sources.list.d/passenger.list'
sudo apt update

# Install Passenger + Apache module
sudo apt install -y libapache2-mod-passenger
sudo apt install -y apache2

# Install Ruby, Rails, Bundler
sudo apt install -y ruby-full build-essential zlib1g-dev
sudo gem install rails bundler

Install on CentOS/RHEL

# See official docs for latest steps: https://www.phusionpassenger.com/library/install/apache/install/oss/el7/

⚙️ Basic Configuration

Create a Rails App

# Create a new Rails app (or clone your repo)
cd /var/www
rails new myapp -d postgresql
cd myapp
bundle install
RAILS_ENV=production rails db:setup
RAILS_ENV=production rails assets:precompile

Apache VirtualHost Example

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/myapp/public
    
        Allow from all
        Options -MultiViews
        Require all granted
    
    ErrorLog ${APACHE_LOG_DIR}/myapp_error.log
    CustomLog ${APACHE_LOG_DIR}/myapp_access.log combined

⚙️ Rails Application Settings for Passenger

• Set RAILS_ENV=production for production deployments
• Precompile assets: RAILS_ENV=production rails assets:precompile
• Use config.force_ssl = true in config/environments/production.rb for HTTPS
• Set secrets and DB credentials via environment variables or config/credentials.yml.enc
• For large apps, tune config.threadsafe! and config.eager_load = true
• Use SetEnv in Apache config to pass ENV vars to Rails

# Example: config/environments/production.rb
Rails.application.configure do
  config.cache_classes = true
  config.eager_load = true
  config.force_ssl = true
  config.log_level = :info
  # ...other production settings...
end

🚀 Full Implementation Example: Rails + Passenger + Apache + SSL

🌐 Passenger with Nginx

Passenger can also be used with Nginx instead of Apache. This is a popular choice for high-performance Rails deployments, as Nginx is lightweight and efficient for serving static files and handling concurrent connections.

Install Passenger + Nginx (Ubuntu/Debian)

# Add Passenger APT repo
sudo apt update
sudo apt install -y dirmngr gnupg apt-transport-https ca-certificates
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 561F9B9CAC40B2F7
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger $(lsb_release -cs) main > /etc/apt/sources.list.d/passenger.list'
sudo apt update

# Install Passenger + Nginx module
sudo apt install -y libnginx-mod-http-passenger nginx

Sample Nginx Config for Rails + Passenger

server {
    listen 80;
    server_name example.com;
    root /var/www/myapp/public;

    passenger_enabled on;
    passenger_app_env production;

    # Static file serving
    location ~ ^/(assets|packs|uploads)/ {
        expires max;
        add_header Cache-Control public;
    }

    # Rails error pages
    error_page 500 502 503 504 /500.html;
    client_max_body_size 20M;
    keepalive_timeout 10;
}

SSL with Nginx + Passenger

server {
    listen 443 ssl;
    server_name example.com;
    root /var/www/myapp/public;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    passenger_enabled on;
    passenger_app_env production;
    # ...rest as above...
}

Environment Variables in Nginx + Passenger

passenger_env_var SECRET_KEY_BASE your_secret;
passenger_env_var DATABASE_URL postgres://user:pass@localhost/dbname;

Troubleshooting Tips:

• App not loading? Check /var/log/nginx/ error.log and log/production.log
• Permission denied? Ensure public/ and tmp/ are writable by the Nginx user (usually www-data).
• Assets not loading? Check root path and precompile assets.
• SSL not working? Check certificate paths and run sudo certbot renew –dry-run.
• Environment variables? Use passenger_env_var in your Nginx config.

🐳 Passenger with Docker

Passenger can be run inside Docker containers for modern, containerized Rails deployments. Official images are available, but Puma is more common in the Docker world. Here’s a basic example:

# Dockerfile for Rails + Passenger + Apache
FROM phusion/passenger-ruby31:latest

# Install dependencies
RUN apt-get update && apt-get install -y nodejs yarn

# Set working directory
WORKDIR /app

# Copy app files
COPY . /app

# Install gems
RUN bundle install

# Precompile assets
RUN bundle exec rake assets:precompile

# Expose port 80
EXPOSE 80

# Start Apache + Passenger
CMD ["/usr/sbin/apache2ctl", "-D", "FOREGROUND"]

🏢 Best Settings for Large Scale Applications

• Increase PassengerMaxPoolSize for more concurrent processes
• Use PassengerMinInstances to keep workers warm
• Enable config.cache_store with Memcached or Redis
• Use a CDN for static assets
• Enable Gzip compression (mod_deflate)
• Monitor with passenger-status and external tools (New Relic, Datadog)
• Set config.active_record.database_selector for DB load balancing (Rails 6+)
• Use config.active_job.queue_adapter for background jobs (Sidekiq, Resque)

# Example: Apache Passenger tuning
PassengerMaxPoolSize 12
PassengerMinInstances 4
PassengerPoolIdleTime 300

🌍 Real-World Case Study: Rails + Passenger Deployment

🚨 Common Error Messages Table

🔄 .htaccess and Nginx Equivalent

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

if ($scheme = http) {
  return 301 https://$host$request_uri;
}

ErrorDocument 404 /404.html

error_page 404 /404.html;

AuthType Basic
AuthName "Restricted"
AuthUserFile /path/to/.htpasswd
Require valid-user

auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;

Header set Access-Control-Allow-Origin "*"

add_header Access-Control-Allow-Origin *;

Options -Indexes

autoindex off;

🔧 Troubleshooting

• Check /var/log/apache2/ error.log for Passenger and Rails errors
• Check log/production.log in your Rails app
• Use passenger-status and passenger-memory-stats for diagnostics
• Restart Apache after config changes: sudo systemctl reload apache2
• Check permissions on public/ and tmp/

⚡ Performance Tuning

• Use PassengerMaxPoolSize to control max app processes
• Enable caching in Rails (config/environments/production.rb)
• Use a CDN for static assets
• Enable Gzip compression (mod_deflate)
• Monitor memory usage with passenger-memory-stats

🔒 Security Best Practices

• Always use HTTPS (SSL/TLS)
• Hide Apache version (ServerTokens Prod, ServerSignature Off)
• Set proper file permissions (never run as root)
• Use strong secrets and environment variables
• Keep Rails, Passenger, and Apache updated
• Enable firewalls and restrict SSH access

🤖 Automation

• Automate deployment with Capistrano or Ansible
• Use bash scripts for backups and log rotation
• Automate SSL renewal with Certbot cron job

# Example: Capistrano deploy
bundle exec cap production deploy

📈 Monitoring

• Use passenger-status and passenger-memory-stats
• Monitor Apache logs and Rails logs
• Integrate with external tools (New Relic, Datadog, etc.)

📝 Passenger + Rails Cheat Sheet

❓ FAQ

🌐 External Resources

• Official Passenger Documentation
• Rails Deployment Guide
• DigitalOcean: Deploy Rails with Apache & Passenger

✅ Conclusion