Skip to main content
The cPanel Setup Ruby App tool registers a Ruby app under your account and serves it through mod_passenger running inside Apache. Ruby is different from Node and Python in one important way: Passenger only ships one Ruby version per server. Every Ruby app on the box runs that version. You can’t mix 3.2 and 3.3 the way you can mix Node 20 and 22.
Need a specific Ruby version? Open a ticket. We’ll tell you what’s installed and, if it’s an option on your plan, schedule an upgrade. Power-plan accounts have more flexibility.

​
What’s installed

The Ruby version is set server-wide. To check it from SSH: 
ruby --version

​
Set up an app

1

Open Setup Ruby App

From cPanel home, scroll to Software and click Setup Ruby App.
Setup Ruby App tool icon
2

Click Create Application

On an empty account, you land on a list page with a + Create Application button.
3

Fill in the form

  • Ruby version: pick from the dropdown (usually only one entry).
  • Application root: directory under your home, e.g. myapp. Created if it doesn’t exist.
  • Application URL: domain dropdown plus optional path. Use / for the root.
  • Application startup file: defaults to config.ru. Rails apps already ship one.
  • Passenger log file: optional. Useful for catching boot errors.
4

Save

Click Create. Passenger starts the app in the background.

​
Manage an app

ButtonWhat it does
Run Bundle InstallReads Gemfile and installs gems into the per-app gem path.
Stop AppHalts Passenger for this app. The URL returns 503.
RestartEquivalent to touch tmp/restart.txt. Reloads the running app.
EditReopens the form. Saving overwrites the .htaccess.
DestroyRemoves Passenger registration and the per-app gem path.

​
The Passenger contract

Standard Rack interface. A config.ru at the application root tells Passenger how to start:
config.ru
require_relative 'app'
run App.new
Rails apps come with config.ru already wired up, no edits needed:
config.ru
# Rails default
require_relative 'config/environment'
run Rails.application
Don’t run rails server. Don’t run rackup. Passenger boots the Rack stack itself.
Calling Rack::Handler::WEBrick.run or starting Puma directly inside the app makes Passenger fail to claim the app. Stick to config.ru.

​
Reference: where things live

WhatPath
Per-app gems~/rubyvenv/<app-root>/<version>/...
Bundler config~/<app-root>/.bundle/
Restart trigger~/<app-root>/tmp/restart.txt
Passenger config~/<app-root>/.htaccess (Selector-managed)
Boot log (if configured)path you set in Passenger log file
From SSH: 
cd ~/myapp
bundle install
The CloudLinux CLI for power users (mostly relevant for support): 
cloudlinux-selector --create-webapp --interpreter ruby --user <user> ...
cloudlinux-selector --destroy-webapp --interpreter ruby --user <user> ...

​
Common issues

Passenger couldn’t boot the Rack app. Check the Passenger log file if you set one. Common causes: missing config.ru, gem version mismatch, bundle install not run yet.
The runtime is using a different gem path than your shell. Run bundle install --deployment from inside the app directory, then restart the app.
assets:precompile can blow past 1 GB on large apps. Compile assets locally and rsync public/assets/ up, or run with RAILS_ENV=production NODE_OPTIONS=--max-old-space-size=512 bundle exec rake assets:precompile.
Long Rails initializers can exceed the default Passenger timeout. Bump it in .htaccess:
PassengerStartTimeout 120
Bundler complains about a missing platform when installing. Add the linux platform to the lockfile from your dev machine:
bundle lock --add-platform x86_64-linux
Commit the updated Gemfile.lock and redeploy.

​
Recipes

Deploy Rails

Rails app, Bundler, asset precompilation.

​
Need a hand?

Open a ticket

Best for anything that needs an account check or a config change on our end.

Live chat

Faster for quick questions during business hours.