Ruby on Rails

Ruby on Rails aka "Rails" is a popular web application framework built with Ruby. Opalstack provides an installer for Rails with Ruby 2.6 served by Puma.

Installation

To install a Rails application follow our general instructions for adding applications and select "Ruby on Rails" as the application type in step 5.

When the installation is complete, the following files and directories will be present in the application directory:

  • start and stop scripts to control the operation of your application.
  • env: a directory containing the Inital Rails gems used by your application.
  • tmp: a directory containing temporary files used by your application
  • myproject: a directory containing a demo Rails project.
  • README: basic info regarding the new application.

Post-installation Steps

Please take the following steps before you begin to use your Rails installation:

  1. Connect your Rails application to a site in your dashboard.

  2. Edit /home/myuser/apps/myapp/myproject/config/environments/development.rb to set config.hosts to include your site's domains. Example:

    config.hosts << "domain.com"
    config.hosts << "www.domain.com"
    
  3. Run the following commands to restart your Rails instance:

    /home/myuser/apps/myapp/stop
    /home/myuser/apps/myapp/start
    

Managing gems for your Rails applications

Rails applications installed via Opalstack's Rails installer use Ruby gems in two locations within the application directory:

  • env which contains application environment for the core Ruby on Rails software
  • myproject (or your own project directory) which contains your Rails project and its dependencies.

Before you can add, remove, upgrade, or downgrade gems in your Rails application directory you must first configure your shell environment by executing the following commands, replacing myapp with your application name and myproject with your project name:

export APPDIR=$HOME/apps/myapp
export PROJECTDIR=$APPDIR/myproject
export GEM_HOME=$APPDIR/env
export PATH=$PROJECTDIR/bin:$GEM_HOME/bin:$PATH

Once you have configured your shell environment you're ready to manage your gems as follows:

Working with gems in your application environment

If you need to install additional gems or modify gems in the application environment:

  1. Prepare your shell environment as described above.

  2. Use the gem command to install the gems that you need.

    For example, if you want to connect your Rails project to a MariaDB database you will need the mysql2 gem which you can install with the following command:

    gem install mysql2
    

Working with gems in your Rails project

If you need to install additional gems or modify gems in your Rails project:

  1. Prepare your shell environment as described above.

  2. Switch to your project directory:

    cd $PROJECTDIR
    
  3. Update the Gemfile in your Rails project directory to specify the gems for your project.

  4. Install the gems with the bundle command:

    bundle install
    

Serving your own Rails project

If you want to serve your own Rails project from a Rails app installed via your Opalstack dashboard:

  1. Upload your project directory to your Rails application directory, for example: /home/myuser/apps/myapp/

  2. SSH to your application's shell user account.

  3. Set your GEM_HOME and PATH environment to your application and then install your project dependencies with bundle:

    export GEM_HOME=$HOME/apps/myapp/env
    export PATH=$HOME/apps/myapp/env/bin:$HOME/apps/myapp/newproject/bin:$PATH
    cd $HOME/apps/myapp/newproject
    bundle install
    
  4. Edit the start and stop scripts in your Rails application directory to change the PROJECTDIR variable on line 4 to point to your project directory.

    For example if your project directory is named newproject you would change this...

    # change the next line to your Rails project directory
    PROJECTDIR='/home/myuser/apps/myapp/myproject'
    

    ... to this ...

    # change the next line to your Rails project directory
    PROJECTDIR='/home/myuser/apps/myapp/newproject'
    
  5. Finally, run the following commands to switch your Rails instance over to your project:

    export APPDIR=$HOME/apps/myapp
    mkdir -p $APPDIR/newproject/tmp/pids
    cp $APPDIR/oldproject/tmp/pids/* $APPDIR/newproject/tmp/pids/
    $APPDIR/stop
    $APPDIR/start
    

Using Databases with Ruby on Rails

PostgreSQL

To use a PostgreSQL database with your Rails project:

  1. Create a new PostgreSQL database and make a note of the following:

    • The database name
    • The database user name
    • The database user password
  2. SSH into your Rails application's shell user account and run the following commands to install the PostgreSQL dependencies for Ruby (substituting myapp with your Rails application name and myproject with your Rails project name):

    export APPDIR=$HOME/apps/myapp
    export PROJECTDIR=$APPDIR/myproject
    export GEM_HOME=$APPDIR/env
    export PATH=/usr/pgsql-11/bin/:$PROJECTDIR/bin:$GEM_HOME/bin:$PATH
    gem install pg
    
  3. Configure your project environment's database.yml section as follows:

    production:
      <<: *default
      adapter: postgresql
      database: your_database_name
      username: your_database_user_name
      password: your_database_user_password
    

MariaDB (MySQL)

Opalstack uses MariaDB for MySQL-compatible database services. To use a MariaDB database with your Rails project:

  1. Create a new MariaDB database and make a note of the following:

    • The database name
    • The database user name
    • The database user password
  2. SSH into your Rails application's shell user account and run the following commands to install the PostgreSQL dependencies for Ruby (substituting myapp with your Rails application name and myproject with your Rails project name):

    export APPDIR=$HOME/apps/myapp
    export PROJECTDIR=$APPDIR/myproject
    export GEM_HOME=$APPDIR/env
    export PATH=$PROJECTDIR/bin:$GEM_HOME/bin:$PATH
    gem install mysql2
    
  3. Configure your project environment's database.yml section as follows:

    production:
      <<: *default
      adapter: mysql2
      database: your_database_name
      username: your_database_user_name
      password: your_database_user_password
    

SQLite

The CentOS operating system used by Opalstack includes a version of SQLite that is too old to be compatible with most current web applications. To work around this, Opalstack maintains a recent version of SQLite in the /opt directory on web servers.

Note: Rails applications installed via our installer use an environment variable in the start script which allows them to use the newer version of SQLite when they are running. However, when you are working with your Rails application at the command line you must configure the environment manually by setting the LD_LIBRARY_PATH variable as shown below.

To use a SQLite database with your Rails project:

  1. SSH into your Rails application's shell user account and configure your shell environment to recognize the updated

    export LD_LIBRARY_PATH=/opt/lib
    
  2. Configure your project environment's database.yml section as follows, substituting db/production.sqlite3 with the path to your SQLite database file:

    production:
      <<: *default
      adapter: sqlite3
      database: db/production.sqlite3