How to configure a Ruby on Rails application on a shared hosting account

This article describes how to use the Setup Ruby App feature in cPanel to configure and run a Ruby on Rails application in a shared hosting environment.

Step 1: Create the application in cPanel

First, you must create the application in cPanel using the Setup Ruby App feature. To do this, follow these steps:

  1. Log in to cPanel.
    If you do not know how to log in to your cPanel account, please see this article.
  2. Open the Ruby App tool:
    • If you are using the Jupiter theme, on the Tools page, in the Software section, click Setup Ruby App:

      cPanel - Software - Setup Ruby App icon

    • If you are using the Paper Lantern theme, in the SOFTWARE section of the cPanel home page, click Setup Ruby App:

      cPanel - Software - Setup Ruby App icon

  3. On the Setup Ruby App page, under Setup New Application, do the following:

    • In the Ruby version list box, select 2.5.
      Ruby 2.6 introduces dependency conflicts and currently does not work with Rails on a shared hosting account. You must use Ruby version 2.5 instead.
    • In the App Directory text box, type the name of the directory where you want to store the application files. For example, type railsapp.
    • In the App Domain/URI list box, select the domain you want to use, and then type the URI in the text box.
  4. Click Setup. cPanel creates the application.
  5. Under Existing applications, locate the application (for example, railsapp).
  6. In the modules row, click show.
  7. In the text box next to Add, type rails and then click Add.
  8. At the bottom of the application section, click Update. cPanel installs the Rails module.
  9. Next to Command for entering to virtual environment, copy the entire command that begins with source. You will use this command in the next procedure.

Step 2: Configure the application from the command line

At this point you have created the Ruby on Rails environment in cPanel. Now you are ready to create and configure the Rails application itself. To do this, follow these steps:

  1. Log in to your account using SSH.
  2. At the command prompt, paste the command you copied in step 9 of the previous procedure. This command activates the Ruby virtual environment.
    To confirm the virtual environment is active after you run the source command, check that the Bash prompt starts with the application name and Ruby version number. For example:
    (railsapp:2.5)example@mi3-ss21 [~]#
  3. Type the following command:


    You must run this command every time after you activate the virtual environment. Alternatively, you can combine this command with the command above to activate the virtual environment. For example:

    source /home/username/rubyvenv/railsapp/2.5/bin/activate && unset XDG_RUNTIME_DIR
  4. To back up the file, type the following commands. Replace railsapp with the name of your own application directory:

    cd ~/railsapp
  5. To create the Rails application, type the following command. Replace railsapp with the name of your own application directory:

    rails new ~/railsapp
  6. To add a default route, open the config/routes.rb file in your preferred text editor. Add the following line after the Rails.application.routes.draw do line:

    root 'rails/welcome#index'
  7. Save your changes to the config/routes.rb file.
  8. In cPanel, restart the application. On the Setup Ruby App page, under Existing applications, locate the application, and then click Restart.
  9. Open the application URI in a web browser, and you should see the Yay! You're on Rails page. You can now add controllers and other components to your Rails application.


If the Ruby on Rails application does not work correctly, you can check the application log files for errors. The application log files are located in the log directory (for example, ~/railsapp/log). There are separate log files for each environment:

  • production.log for the production environment.
  • development.log for the development environment.

If you need further assistance, please open a support ticket with our Guru Crew on the Customer Portal at

More Information

Get Ruby on Rails Hosting

Article Details

Did you find this article helpful? Then you'll love our support. Experience the A2 Hosting difference today and get a pre-secured, pre-optimized website. Check out our web hosting plans today.

We use cookies to personalize the website for you and to analyze the use of our website. You consent to this by clicking on "I consent" or by continuing your use of this website. Further information about cookies can be found in our Privacy Policy.