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:

​
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

cPanel home → Software → Setup Ruby App

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

​
The Passenger contract

Standard Rack interface. A config.ru at the application root tells Passenger how to start:
config.ru
Rails apps come with config.ru already wired up, no edits needed:
config.ru
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

From SSH:
The CloudLinux CLI for power users (mostly relevant for support):

​
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:
Bundler complains about a missing platform when installing. Add the linux platform to the lockfile from your dev machine:
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.