Using Ruby on Rails

Ruby on Rails is a web framework written in Ruby. This guide covers using Rails 4 on OKD.

Go through the whole tutorial to have an overview of all the steps necessary to run your application on the OKD. If you experience a problem try reading through the entire tutorial and then going back to your issue. It can also be useful to review your previous steps to ensure that all the steps were run correctly.

Prerequisites

  • Basic Ruby and Rails knowledge.

  • Locally installed version of Ruby 2.0.0+, Rubygems, Bundler.

  • Basic Git knowledge.

  • Running instance of OKD 4.

  • Make sure that an instance of OKD is running and is available. Also make sure that your oc CLI client is installed and the command is accessible from your command shell, so you can use it to log in using your email address and password.

Setting up the database

Rails applications are almost always used with a database. For local development use the PostgreSQL database.

Procedure

  1. Install the database:

    1. $ sudo yum install -y postgresql postgresql-server postgresql-devel
  2. Initialize the database:

    1. $ sudo postgresql-setup initdb

    This command creates the /var/lib/pgsql/data directory, in which the data is stored.

  3. Start the database:

    1. $ sudo systemctl start postgresql.service
  4. When the database is running, create your rails user:

    1. $ sudo -u postgres createuser -s rails

    Note that the user created has no password.

Writing your application

If you are starting your Rails application from scratch, you must install the Rails gem first. Then you can proceed with writing your application.

Procedure

  1. Install the Rails gem:

    1. $ gem install rails

    Example output

    1. Successfully installed rails-4.3.0
    2. 1 gem installed
  2. After you install the Rails gem, create a new application with PostgreSQL as your database:

    1. $ rails new rails-app --database=postgresql
  3. Change into your new application directory:

    1. $ cd rails-app
  4. If you already have an application, make sure the pg (postgresql) gem is present in your Gemfile. If not, edit your Gemfile by adding the gem:

    1. gem 'pg'
  5. Generate a new Gemfile.lock with all your dependencies:

    1. $ bundle install
  6. In addition to using the postgresql database with the pg gem, you also must ensure that the config/database.yml is using the postgresql adapter.

    Make sure you updated default section in the config/database.yml file, so it looks like this:

    1. default: &default
    2. adapter: postgresql
    3. encoding: unicode
    4. pool: 5
    5. host: localhost
    6. username: rails
    7. password:
  7. Create your application’s development and test databases:

    1. $ rake db:create

    This creates development and test database in your PostgreSQL server.

Creating a welcome page

Since Rails 4 no longer serves a static public/index.html page in production, you must create a new root page.

In order to have a custom welcome page must do following steps:

  • Create a controller with an index action.

  • Create a view page for the welcome controller index action.

  • Create a route that serves applications root page with the created controller and view.

Rails offers a generator that completes all necessary steps for you.

Procedure

  1. Run Rails generator:

    1. $ rails generate controller welcome index

    All the necessary files are created.

  2. edit line 2 in config/routes.rb file as follows:

    1. root 'welcome#index'
  3. Run the rails server to verify the page is available:

    1. $ rails server

    You should see your page by visiting http://localhost:3000 in your browser. If you do not see the page, check the logs that are output to your server to debug.

Configuring application for OKD

To have your application communicate with the PostgreSQL database service running in OKD you must edit the default section in your config/database.yml to use environment variables, which you must define later, upon the database service creation.

Procedure

  • Edit the default section in your config/database.yml with pre-defined variables as follows:

    Sample config/database YAML file

    1. <% user = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? "root" : ENV["POSTGRESQL_USER"] %>
    2. <% password = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? ENV["POSTGRESQL_ADMIN_PASSWORD"] : ENV["POSTGRESQL_PASSWORD"] %>
    3. <% db_service = ENV.fetch("DATABASE_SERVICE_NAME","").upcase %>
    4. default: &default
    5. adapter: postgresql
    6. encoding: unicode
    7. # For details on connection pooling, see rails configuration guide
    8. # http://guides.rubyonrails.org/configuring.html#database-pooling
    9. pool: <%= ENV["POSTGRESQL_MAX_CONNECTIONS"] || 5 %>
    10. username: <%= user %>
    11. password: <%= password %>
    12. host: <%= ENV["#{db_service}_SERVICE_HOST"] %>
    13. port: <%= ENV["#{db_service}_SERVICE_PORT"] %>
    14. database: <%= ENV["POSTGRESQL_DATABASE"] %>

Storing your application in Git

Building an application in OKD usually requires that the source code be stored in a git repository, so you must install git if you do not already have it.

Prerequisites

  • Install git.

Procedure

  1. Make sure you are in your Rails application directory by running the ls -1 command. The output of the command should look like:

    1. $ ls -1

    Example output

    1. app
    2. bin
    3. config
    4. config.ru
    5. db
    6. Gemfile
    7. Gemfile.lock
    8. lib
    9. log
    10. public
    11. Rakefile
    12. README.rdoc
    13. test
    14. tmp
    15. vendor
  2. Run the following commands in your Rails app directory to initialize and commit your code to git:

    1. $ git init
    1. $ git add .
    1. $ git commit -m "initial commit"

    After your application is committed you must push it to a remote repository. GitHub account, in which you create a new repository.

  3. Set the remote that points to your git repository:

    1. $ git remote add origin git@github.com:<namespace/repository-name>.git
  4. Push your application to your remote git repository.

    1. $ git push

Deploying your application to OKD

You can deploy you application to OKD.

After creating the rails-app project, you are automatically switched to the new project namespace.

Deploying your application in OKD involves three steps:

  • Creating a database service from OKD’s PostgreSQL image.

  • Creating a frontend service from OKD’s Ruby 2.0 builder image and your Ruby on Rails source code, which are wired with the database service.

  • Creating a route for your application.

Procedure

  • To deploy your Ruby on Rails application, create a new project for the application:

    1. $ oc new-project rails-app --description="My Rails application" --display-name="Rails Application"

Creating the database service

Your Rails application expects a running database service. For this service use PostgreSQL database image.

To create the database service, use the oc new-app command. To this command you must pass some necessary environment variables which are used inside the database container. These environment variables are required to set the username, password, and name of the database. You can change the values of these environment variables to anything you would like. The variables are as follows:

  • POSTGRESQL_DATABASE

  • POSTGRESQL_USER

  • POSTGRESQL_PASSWORD

Setting these variables ensures:

  • A database exists with the specified name.

  • A user exists with the specified name.

  • The user can access the specified database with the specified password.

Procedure

  1. Create the database service:

    1. $ oc new-app postgresql -e POSTGRESQL_DATABASE=db_name -e POSTGRESQL_USER=username -e POSTGRESQL_PASSWORD=password

    To also set the password for the database administrator, append to the previous command with:

    1. -e POSTGRESQL_ADMIN_PASSWORD=admin_pw
  2. Watch the progress:

    1. $ oc get pods --watch

Creating the frontend service

To bring your application to OKD, you must specify a repository in which your application lives.

Procedure

  1. Create the frontend service and specify database related environment variables that were setup when creating the database service:

    1. $ oc new-app path/to/source/code --name=rails-app -e POSTGRESQL_USER=username -e POSTGRESQL_PASSWORD=password -e POSTGRESQL_DATABASE=db_name -e DATABASE_SERVICE_NAME=postgresql

    With this command, OKD fetches the source code, sets up the builder builds your application image, and deploys the newly created image together with the specified environment variables. The application is named rails-app.

  2. Verify the environment variables have been added by viewing the JSON document of the rails-app deployment config:

    1. $ oc get dc rails-app -o json

    You should see the following section:

  3. Example output

  1. env": [
  2. {
  3. "name": "POSTGRESQL_USER",
  4. "value": "username"
  5. },
  6. {
  7. "name": "POSTGRESQL_PASSWORD",
  8. "value": "password"
  9. },
  10. {
  11. "name": "POSTGRESQL_DATABASE",
  12. "value": "db_name"
  13. },
  14. {
  15. "name": "DATABASE_SERVICE_NAME",
  16. "value": "postgresql"
  17. }
  18. ],
  1. Check the build process:

    1. $ oc logs -f build/rails-app-1
  2. Once the build is complete, look at the running pods in OKD:

    1. $ oc get pods

    You should see a line starting with myapp-<number>-<hash>, and that is your application running in OKD.

  3. Before your application is functional, you must initialize the database by running the database migration script. There are two ways you can do this:

    • Manually from the running frontend container:

      • Exec into frontend container with rsh command:

        1. $ oc rsh <frontend_pod_id>
      • Run the migration from inside the container:

        1. $ RAILS_ENV=production bundle exec rake db:migrate

        If you are running your Rails application in a development or test environment you do not have to specify the RAILS_ENV environment variable.

    • By adding pre-deployment lifecycle hooks in your template.

Creating a route for your application

You can expose a service to create a route for your application.

Procedure

  • To expose a service by giving it an externally-reachable hostname like www.example.com use OKD route. In your case you need to expose the frontend service by typing:

    1. $ oc expose service rails-app --hostname=www.example.com

Ensure the hostname you specify resolves into the IP address of the router.