Skip to main content
Updated: August 9, 2026
Matic Bončina
By Matic BončinaFounder
✓Proofread & verified
Setup Ruby App registers a Ruby application under your cPanel account and hands it to Phusion Passenger, which boots your Rack app and keeps it running. You give it three things: a Ruby version, a directory, and the address you want it served from.
Ruby is included on BONFIRE, BLAZE and INFERMO. SPARK and FLAME don’t come with it, so those plans need an upgrade before any of this works.

​
Ruby versions

You choose the version per application, so two apps in the same account can run different ones. The setup form currently offers: 3.2 (preselected), 3.1, 3.0, 2.7, 2.6, 2.5, 2.4, 2.3, 2.2 Take the newest one your Gemfile supports. If you need something that isn’t in the list, open a ticket and we’ll tell you whether we can add it.

​
Set up an app

1

Open Setup Ruby App

From cPanel home, scroll to Software and click Setup Ruby App.
The Software section of cPanel home, with Setup Ruby App in the third row beside Setup Node.js App and Setup Python App

cPanel home → Software → Setup Ruby App

2

Fill in the form

The page opens straight onto Setup new application, with three things to set:
  • Ruby version: the interpreter this app runs on.
  • App Directory: a folder under your home directory, such as myapp. Your config.ru and Gemfile go here.
  • App Domain/URI: choose a domain, then add a path if you want one. Leave the path box empty to serve the app at the domain root.
The Setup new application form with the Ruby version dropdown set to 3.2, an empty App Directory field under /home, and the App Domain/URI domain picker

Setup Ruby App → Setup new application

3

Click Setup

The app is created and listed under Existing applications at the bottom of the same page.

​
Manage an app

Apps you’ve already created appear under Existing applications, below the setup form. Each one gets a row of its own.
An existing Ruby application row showing App Directory and App URI with Edit links, a Ruby version dropdown, a modules show link, an Execute command box with a Run button, the source activate command, and the Update, Reset, Restart and Remove buttons

Setup Ruby App → Existing applications

There’s no stop button. Removing the app is the only way to take it offline from here.

​
The Passenger contract

Passenger speaks plain Rack. A config.ru in your app directory tells it 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.
Booting your own server inside the app, whether that’s WEBrick through a Rack handler or Puma started by hand, stops Passenger claiming the app. Let config.ru be the entry point and nothing else.

​
Work on the app over SSH

Each app gets its own gem environment under ~/rubyvenv/<app-directory>/<version>/. Your login shell doesn’t use it by default, which is why a gem can be installed and still be missing at runtime. The app row prints the exact line to fix that. Copy it from Command for entering to virtual environment and run it before anything else:
After installing gems, hit Restart on the app row so Passenger picks them up.

​
Common issues

Passenger couldn’t boot the Rack app. Check config.ru exists in the app directory, that your gems are installed, and that the Ruby version on the app row matches what your Gemfile asks for. Restart after each change.
Your shell and the app are reading different gem paths. Activate the app’s environment first, then reinstall:
Then Restart the app so it picks the gems up.To pin the app to its lockfile, use bundle config set --local deployment true. The older bundle install --deployment flag was deprecated in Bundler 2.1.
assets:precompile is the hungriest step in a Rails deploy. Compile locally and copy public/assets/ up, or cap the JavaScript runtime:
Passenger’s default start timeout is 90 seconds, and a long chain of Rails initializers can outrun it. Trim what runs at boot first, since that helps every request afterwards. If the app genuinely needs longer, open a ticket and we’ll look at the timeout for you.
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.