Ruby on Rails

Ruby on Rails aka "Rails" is a popular web application framework built with Ruby.

Opalstack provides an installer for Rails served by Nginx and Puma.

This documentation is applicable to Rails apps installed on Opalstack after April 2022. If you installed a Rails app on Opalstack prior to that date please see our old Rails documentation.

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, stop, and restart: scripts to control the operation of your application. There are also scripts to control the Puma and Nginx servers individually.
  • setenv: a script that you can source to setup your shell environment when working with your Rails app.
  • env: a directory containing the Rails gems used to bootstrap your application.
  • tmp: a directory containing temporary files used by your application
  • myproject: a directory containing a demo Rails project.
  • nginx: a directory containing the Nginx configuration for your application.
  • 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. Edit /home/myuser/apps/myapp/nginx/nginx.conf to set server_name to include your site's domains. Example:

    server_name domain.com www.domain.com;

  4. Run the following command to restart your Rails instance:

    /home/myuser/apps/myapp/restart

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:

cd ~/apps/myapp
source setenv

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.

    gem install name_of_gem

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 /home/myuser/apps/myapp.

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

  3. Edit /home/myuser/apps/myapp/setenv to set PROJECTDIR to your project directory, eg:

    PROJECTDIR=$HOME/app/$APPNAME/yourproject

  4. Set your environment for your application:

    cd /home/myuser/apps/myapp
source setenv

  5. Install your project dependencies with bundle:

    cd /home/myuser/apps/myapp/yourproject
bundle install

  6. Edit /home/myuser/apps/myapp/start_puma and /home/myuser/apps/myapp/stop_puma to change the PROJECTDIR variable to point to your project directory, for example:

    PROJECTDIR=$HOME/apps/$APPNAME/yourproject

  7. Edit /home/myuser/apps/myapp/nginx.conf to change the Puma socket path and server root to point to your project directory, for example:

    ...
upstream puma {
  server unix:/home/myuser/apps/app_name/yourproject/tmp/sockets/puma.sock fail_timeout=0;
}

server {
    # change the next two lines to use your site domain
    # and your project's public directory
    server_name localhost;
    root /home/myuser/apps/app_name/yourproject;
...

  8. Run the following commands to restart your Rails instance:

    mkdir -p /home/myuser/apps/myapp/yourproject/tmp/pids
mkdir -p /home/myuser/apps/myapp/yourproject/tmp/sockets
cp /home/myuser/apps/myapp/oldproject/tmp/pids/* /home/myuser/apps/myapp/yourproject/tmp/pids/
/home/myuser/apps/myapp/restart

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. Edit your project's Gemfile to include the pg gem like so:

    gem "pg"

  3. 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):

    cd ~/apps/myapp
source setenv
export PATH=/usr/pgsql-11/bin/:$PATH
cd myproject
bundle install

  4. 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. Edit your project's Gemfile to include the mysql2 gem like so:

    gem "mysql2"

  3. SSH into your Rails application's shell user account and run the following commands to install the MariaDB dependencies for Ruby (substituting myapp with your Rails application name and myproject with your Rails project name):

    cd ~/apps/myapp
source setenv
cd myproject
bundle install

  4. 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 /usr/sqlite330 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 newer SQLite:

    cd ~/apps/myapp
source setenv
export PATH=/usr/sqlite330/bin:$PATH
export LD_LIBRARY_PATH=/usr/sqlite330/lib:$LD_LIBRARY_PATH

  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