> ## Documentation Index
> Fetch the complete documentation index at: https://help.noxity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby

> Run Ruby apps on cPanel via the Ruby Selector. mod_passenger, Bundler, Rails-friendly. The Ruby version is set server-wide.

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.

<Info>
  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.
</Info>

## What's installed

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

```bash theme={}
ruby --version
```

## Set up an app

<Steps>
  <Step title="Open Setup Ruby App">
    From cPanel home, scroll to **Software** and click **Setup Ruby App**.

    <Frame caption="cPanel home → Software → Setup Ruby App">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/noxity/images/web-hosting/virtual-containers/ruby/open-light.png" alt="Setup Ruby App tool icon" className="block dark:hidden" />

      <img src="https://mintlify.s3.us-west-1.amazonaws.com/noxity/images/web-hosting/virtual-containers/ruby/open-dark.png" alt="Setup Ruby App tool icon" className="hidden dark:block" />
    </Frame>
  </Step>

  <Step title="Click Create Application">
    On an empty account, you land on a list page with a **+ Create Application** button.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save">
    Click **Create**. Passenger starts the app in the background.
  </Step>
</Steps>

## Manage an app

| Button                 | What it does                                                    |
| ---------------------- | --------------------------------------------------------------- |
| **Run Bundle Install** | Reads `Gemfile` and installs gems into the per-app gem path.    |
| **Stop App**           | Halts Passenger for this app. The URL returns 503.              |
| **Restart**            | Equivalent to `touch tmp/restart.txt`. Reloads the running app. |
| **Edit**               | Reopens the form. Saving overwrites the `.htaccess`.            |
| **Destroy**            | Removes 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:

```ruby config.ru theme={}
require_relative 'app'
run App.new
```

Rails apps come with `config.ru` already wired up, no edits needed:

```ruby config.ru theme={}
# Rails default
require_relative 'config/environment'
run Rails.application
```

Don't run `rails server`. Don't run `rackup`. Passenger boots the Rack stack itself.

<Warning>
  Calling `Rack::Handler::WEBrick.run` or starting Puma directly inside the app makes Passenger fail to claim the app. Stick to `config.ru`.
</Warning>

## Reference: where things live

| What                     | Path                                        |
| ------------------------ | ------------------------------------------- |
| 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:

```bash theme={}
cd ~/myapp
bundle install
```

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

```bash theme={}
cloudlinux-selector --create-webapp --interpreter ruby --user <user> ...
cloudlinux-selector --destroy-webapp --interpreter ruby --user <user> ...
```

## Common issues

<AccordionGroup>
  <Accordion title="App returns 503 on every request">
    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.
  </Accordion>

  <Accordion title="Gem 'X' not found at runtime, but `bundle list` shows it">
    The runtime is using a different gem path than your shell. Run `bundle install --deployment` from inside the app directory, then restart the app.
  </Accordion>

  <Accordion title="Asset precompilation OOMs on a Rails 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`.
  </Accordion>

  <Accordion title="Boot times out after 60 seconds">
    Long Rails initializers can exceed the default Passenger timeout. Bump it in `.htaccess`:

    ```apache theme={}
    PassengerStartTimeout 120
    ```
  </Accordion>

  <Accordion title="Gemfile.lock platform mismatch">
    Bundler complains about a missing platform when installing. Add the linux platform to the lockfile from your dev machine:

    ```bash theme={}
    bundle lock --add-platform x86_64-linux
    ```

    Commit the updated `Gemfile.lock` and redeploy.
  </Accordion>
</AccordionGroup>

## Recipes

<CardGroup cols={2}>
  <Card title="Deploy Rails" icon="train" href="/how-to/virtual-containers/ruby/rails">Rails app, Bundler, asset precompilation.</Card>
</CardGroup>

## Need a hand?

<CardGroup cols={2}>
  <Card title="Open a ticket" icon="life-ring" href="https://members.noxity.io/submitticket.php">
    Best for anything that needs an account check or a config change on our end.
  </Card>

  <Card title="Live chat" icon="messages" href="https://noxity.io/contact">
    Faster for quick questions during business hours.
  </Card>
</CardGroup>

<div className="mt-8">
  <Accordion title="Sources" icon="book-bookmark">
    * [Virtual Containers overview](/web-hosting/virtual-containers/overview)
    * [Setup Ruby App ↗](https://docs.cpanel.net/cpanel/software/setup-ruby-app/)
    * [CloudLinux Ruby Selector ↗](https://docs.cloudlinux.com/cloudlinuxos/cloudlinux_os_components/#ruby-selector)
    * [Phusion Passenger Ruby ↗](https://www.phusionpassenger.com/library/walkthroughs/start/ruby.html)
  </Accordion>
</div>