Creating applications using Ruby on Rails - Creating applications | Building applications

Prerequisites
Setting up the database
Writing your application
Deploying your application to OKD

You can build and deploy a Ruby on Rails 4 application on OKD by developing it locally.

Store the source in Git, then deploy the database, frontend, and route services. With this process, you can validate your application locally before deploying it to the cluster as a set of distinct services.

You must complete each part of this tutorial in order to before you deploy your application on OKD. If a step fails, confirm that every preceding step completed successfully before you continue.

Prerequisites

You have basic Ruby on Rails knowledge.
You have Ruby 2.0.0+, Rubygems, and Bundler installed locally.
You have basic Git knowledge.
You have a running instance of OKD 4.
The OpenShift CLI (oc) installed.
You are logged into a running OKD cluster.

Setting up the database

You can install PostgreSQL on your local system for Ruby on Rails development. This gives your application a local database to connect to during development and testing before you deploy to OKD.

Procedure

Install the database by running the following command:

$ sudo yum install -y postgresql postgresql-server postgresql-devel

Initialize the database by running the following command:
```
$ sudo postgresql-setup initdb
```
This command creates the /var/lib/pgsql/data directory, in which the data is stored.
Start the database by running the following command:
```
$ sudo systemctl start postgresql.service
```
When the database is running, create your rails user by running the following command:
```
$ sudo -u postgres createuser -s rails
```
The user that is created has no password.

Writing your application

You can create a Ruby on Rails application that uses PostgreSQL. Install the Rails gem, configure the database.yml file, and initialize the development and test databases. These steps ensure that your application can interact with PostgreSQL in both development and test environments.

Procedure

Install the Rails gem by running the following command:

$ gem install rails

Example output

Successfully installed rails-4.3.0
1 gem installed

Create a new application with PostgreSQL as your database by running the following command:
```
$ rails new rails-app --database=postgresql
```
Change into your new application directory by running the following command:
```
$ cd rails-app
```
If you already have an application, ensure that the PostgreSQL adapter gem (pg) is present in your Gemfile. If not, edit your Gemfile by adding the gem:
```
gem 'pg'
```
Generate a new Gemfile.lock with all your dependencies by running the following command:
```
$ bundle install
```

Update the default section in the config/database.yml file to use the postgresql adapter, as shown in the following example:

default: &default
  adapter: postgresql
  encoding: unicode
  pool: 5
  host: localhost
  username: rails
  password: <password>

Create the development and test databases for your application by running the following command:
```
$ rake db:create
```

Creating a welcome page

You can run the Rails generator to create a custom welcome page for your Rails application. A welcome page gives you content to display when you run the Rails server and open the application in your browser.

Procedure

Run the Rails generator by running the following command:
```
$ rails generate controller welcome index
```
The command creates all the necessary files.
Edit line 2 in the config/routes.rb file as follows:
```
root 'welcome#index'
```
Run the Rails server to verify that the page is available by running the following command:
```
$ rails server
```
Verify that the page is available by visiting http://localhost:3000 in your browser. If the page does not display, check the server logs for errors.

Configuring application for OKD

To configure your Rails application for OKD, you must edit the default section in the config/database.yml file. This is required for OKD to supply the correct database credentials at runtime so your application can connect to PostgreSQL on the cluster.

Procedure

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

Sample config/database YAML file

<% user = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? "root" : ENV["POSTGRESQL_USER"] %>
<% password = ENV.key?("POSTGRESQL_ADMIN_PASSWORD") ? ENV["POSTGRESQL_ADMIN_PASSWORD"] : ENV["POSTGRESQL_PASSWORD"] %>
<% db_service = ENV.fetch("DATABASE_SERVICE_NAME","").upcase %>

default: &default
  adapter: postgresql
  encoding: unicode
  # For details on connection pooling, see rails configuration guide
  # http://guides.rubyonrails.org/configuring.html#database-pooling
  pool: <%= ENV["POSTGRESQL_MAX_CONNECTIONS"] || 5 %>
  username: <%= user %>
  password: <%= password %>
  host: <%= ENV["#{db_service}_SERVICE_HOST"] %>
  port: <%= ENV["#{db_service}_SERVICE_PORT"] %>
  database: <%= ENV["POSTGRESQL_DATABASE"] %>

Storing your application in Git

You can commit your Rails application to Git and push the source to a remote repository. Remote storage keeps your source available for deployment on OKD.

Prerequisites

You have installed Git.

Procedure

Verify that you are in your Rails application directory by running the following command:

$ ls -1

Example output

app
bin
config
config.ru
db
Gemfile
Gemfile.lock
lib
log
public
Rakefile
README.rdoc
test
tmp
vendor

Initialize a Git repository in your Rails application directory by running the following command:
```
$ git init
```
Stage all application files by running the following command:
```
$ git add .
```
Commit the staged files by running the following command:
```
$ git commit -m "initial commit"
```
Create a GitHub repository for your application.
Set the remote that points to your git repository by running the following command:
```
$ git remote add origin git@github.com:<namespace/repository-name>.git
```
Push your application to your remote Git repository by running the following command:
```
$ git push
```

Deploying your application to OKD

You can create an OKD project to deploy your Ruby on Rails application. This separates your database, frontend, and route into distinct services that OKD can manage independently.

Deploying your application on OKD takes three steps:

Creating a database service from the PostgreSQL image on OKD.
Creating a frontend service from the Ruby 2.0 builder image on OKD and your Ruby on Rails source code, connected to the database service.
Creating a route for your application.

Procedure

Create a project for your Rails application by running the following command:

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

Creating the database service

You must create a database service for your Rails application. Be sure to set the environment variables for the database name, username, and password. These are required for the service to connect correctly to your Rails application.

You can change the values of these environment variables to any values you choose. The variables are as follows:

POSTGRESQL_DATABASE
POSTGRESQL_USER
POSTGRESQL_PASSWORD

Setting these variables ensures that the following occurs:

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

Create the database service by running the following command:
```
$ oc new-app postgresql -e POSTGRESQL_DATABASE=db_name -e POSTGRESQL_USER=username -e POSTGRESQL_PASSWORD=password
```
To also set a database administrator password, add -e POSTGRESQL_ADMIN_PASSWORD=admin_pw to the command.
Monitor the pod status by running the following command:
```
$ oc get pods --watch
```

Creating the frontend service

You can create a frontend service with the oc new-app command. Specifying your source repository and database environment variables enables OKD to build your application image and deploy it on the cluster.

Procedure

Create the frontend service and specify the database-related environment variables that were set up when creating the database service by running the following command:
```
$ 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.

Verify that the environment variables have been added by viewing the JSON document of the rails-app deployment config by running the following command:

$ oc get dc rails-app -o json

The output includes the following section:

Example output

env": [
    {
        "name": "POSTGRESQL_USER",
        "value": "username"
    },
    {
        "name": "POSTGRESQL_PASSWORD",
        "value": "password"
    },
    {
        "name": "POSTGRESQL_DATABASE",
        "value": "db_name"
    },
    {
        "name": "DATABASE_SERVICE_NAME",
        "value": "postgresql"
    }

],

Check the build process by running the following command:
```
$ oc logs -f build/rails-app-1
```
After the build is complete, check the running pods in OKD by running the following command:
```
$ oc get pods
```
The output includes a line starting with myapp-<number>-<hash>, which confirms that the application is running in OKD.
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:
  - Open a remote shell to the frontend pod by running the following command:
    
    $ oc rsh <frontend_pod_id>
  - Run the migration from inside the container by running the following command:
    
    $ 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.
- You can also run the migration by adding pre-deployment lifecycle hooks to your template.

Creating a route for your application

You can create a route for your application with the oc expose service command. The route makes the application accessible from outside the cluster.

Procedure

Make the frontend service accessible externally by running the following command:
```
$ oc expose service rails-app --hostname=www.example.com
```
Ensure that the hostname you specify resolves to the IP address of the router.