[OSDOCS#17160] using-ruby CQA

applications/creating_applications/templates-using-ruby-on-rails.adoc

@@ -6,25 +6,29 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Ruby on Rails is a web framework written in Ruby. This guide covers using Rails 4 on {product-title}.
+[role="_abstract"]
+You can build and deploy a Ruby on Rails 4 application on {product-title} 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.
 
 [WARNING]
 ====
-Go through the whole tutorial to have an overview of all the steps necessary to run your application on the {product-title}. 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.
+You must complete each part of this tutorial in order to before you deploy your application on {product-title}. If a step fails, confirm that every preceding step completed successfully before you continue.
 ====
 
 == Prerequisites
 
-* Basic Ruby and Rails knowledge.
-* Locally installed version of Ruby 2.0.0+, Rubygems, Bundler.
-* Basic Git knowledge.
+* You have basic Ruby on Rails knowledge.
+* You have Ruby 2.0.0+, Rubygems, and Bundler installed locally.
+* You have basic Git knowledge.
 ifndef::openshift-online[]
-* Running instance of {product-title} 4.
+* You have a running instance of {product-title} 4.
 endif::[]
 ifdef::openshift-online[]
-* Provisioned account in OpenShift Online.
+* You have a provisioned account in OpenShift Online.
 endif::[]
-* Make sure that an instance of {product-title} 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.
+* The {oc-first} installed.
+* You are logged into a running {product-title} cluster.
 
 include::modules/templates-rails-setting-up-database.adoc[leveloffset=+1]
 

modules/templates-rails-configuring-application.adoc

@@ -5,7 +5,8 @@
 [id="templates-rails-configuring-application_{context}"]
 = Configuring application for {product-title}
 
-To have your application communicate with the PostgreSQL database service running in {product-title} 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.
+[role="_abstract"]
+To configure your Rails application for {product-title}, you must edit the `default` section in the `config/database.yml` file. This is required for {product-title} to supply the correct database credentials at runtime so your application can connect to PostgreSQL on the cluster.
 
 .Procedure
 

modules/templates-rails-creating-database-service.adoc

@@ -5,37 +5,36 @@
 [id="templates-rails-creating-database-service_{context}"]
 = Creating the database service
 
-Your Rails application expects a running database service. For this service use PostgreSQL database image.
+[role="_abstract"]
+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.
 
-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:
+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
+* `POSTGRESQL_DATABASE`
+* `POSTGRESQL_USER`
+* `POSTGRESQL_PASSWORD`
 
-Setting these variables ensures:
+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:
+. Create the database service by running the following command:
 +
 [source,terminal]
 ----
 $ 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:
-+
-[source,terminal]
-----
--e POSTGRESQL_ADMIN_PASSWORD=admin_pw
-----
+[NOTE]
+====
+To also set a database administrator password, add `-e POSTGRESQL_ADMIN_PASSWORD=admin_pw` to the command.
+====
 
-. Watch the progress:
+. Monitor the pod status by running the following command:
 +
 [source,terminal]
 ----

modules/templates-rails-creating-frontend-service.adoc

@@ -5,11 +5,12 @@
 [id="templates-rails-creating-frontend-service_{context}"]
 = Creating the frontend service
 
-To bring your application to {product-title}, you must specify a repository in which your application lives.
+[role="_abstract"]
+You can create a frontend service with the `oc new-app` command. Specifying your source repository and database environment variables enables {product-title} to build your application image and deploy it on the cluster.
 
 .Procedure
 
-. Create the frontend service and specify database related environment variables that were setup when creating the database service:
+. 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:
 +
 [source,terminal]
 ----
@@ -18,14 +19,14 @@ $ oc new-app path/to/source/code --name=rails-app -e POSTGRESQL_USER=username -e
 +
 With this command, {product-title} 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 the environment variables have been added by viewing the JSON document of the `rails-app` deployment config:
+. Verify that the environment variables have been added by viewing the JSON document of the `rails-app` deployment config by running the following command:
 +
 [source,terminal]
 ----
 $ oc get dc rails-app -o json
 ----
 +
-You should see the following section:
+The output includes the following section:
 +
 .Example output
 [source,json]
@@ -51,40 +52,40 @@ env": [
 ],
 ----
 
-. Check the build process:
+. Check the build process by running the following command:
 +
 [source,terminal]
 ----
 $ oc logs -f build/rails-app-1
 ----
 
-. After the build is complete, look at the running pods in {product-title}:
+. After the build is complete, check the running pods in {product-title} by running the following command:
 +
 [source,terminal]
 ----
 $ oc get pods
 ----
 +
-You should see a line starting with `myapp-<number>-<hash>`, and that is your application running in {product-title}.
+The output includes a line starting with `myapp-<number>-<hash>`, which confirms that the application is running in {product-title}.
 
 . 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:
+** Open a remote shell to the frontend pod by running the following command:
 +
 [source,terminal]
 ----
 $ oc rsh <frontend_pod_id>
 ----
 +
-** Run the migration from inside the container:
+** Run the migration from inside the container by running the following command:
 +
 [source,terminal]
 ----
 $ 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.
+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.
+* You can also run the migration by adding pre-deployment lifecycle hooks to your template.

modules/templates-rails-creating-route-for-application.adoc

@@ -5,32 +5,21 @@
 [id="templates-rails-creating-route-for-application_{context}"]
 = Creating a route for your application
 
-You can expose a service to create a route for your application.
+[role="_abstract"]
+You can create a route for your application with the `oc expose service` command. The route makes the application accessible from outside the cluster.
 
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
 .Procedure
 
-* To expose a service by giving it an externally-reachable hostname like `www.example.com` use {product-title} route. In your case you need to expose the frontend service by typing:
+* Make the frontend service accessible externally by running the following command:
 +
 [source,terminal]
 ----
 $ oc expose service rails-app --hostname=www.example.com
 ----
-endif::[]
-
-
-ifdef::openshift-online[]
-.Procedure
-
-* Expose the frontend service by typing:
 +
-[source,terminal]
-----
-$ oc expose service rails-app
-----
-endif::[]
-
 [WARNING]
 ====
-Ensure the hostname you specify resolves into the IP address of the router.
+Ensure that the hostname you specify resolves to the IP address of the router.
 ====
+endif::openshift-enterprise,openshift-webscale,openshift-origin[]

modules/templates-rails-creating-welcome-page.adoc

@@ -5,38 +5,32 @@
 [id="templates-rails-creating-welcome-page_{context}"]
 = 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.
-
-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.
+[role="_abstract"]
+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 Rails generator:
+. Run the Rails generator by running the following command:
 +
 [source,terminal]
 ----
 $ rails generate controller welcome index
 ----
 +
-All the necessary files are created.
+The command creates all the necessary files.
 
-. edit line 2 in `config/routes.rb` file as follows:
+. Edit line 2 in the `config/routes.rb` file as follows:
 +
+[source,ruby]
 ----
 root 'welcome#index'
 ----
 
-. Run the rails server to verify the page is available:
+. Run the Rails server to verify that the page is available by running the following command:
 +
 [source,terminal]
 ----
 $ 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.
+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.

modules/templates-rails-deploying-application.adoc

@@ -5,21 +5,19 @@
 [id="templates-rails-deploying-application_{context}"]
 = Deploying your application to {product-title}
 
-You can deploy you application to {product-title}.
+[role="_abstract"]
+You can create an {product-title} project to deploy your Ruby on Rails application. This separates your database, frontend, and route into distinct services that {product-title} can manage independently.
 
-After creating the `rails-app` project, you are automatically switched to the new project namespace.
+Deploying your application on {product-title} takes three steps:
 
-Deploying your application in {product-title} involves three steps:
-
-* Creating a database service from {product-title}'s PostgreSQL image.
-* Creating a frontend service from {product-title}'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.
+. Creating a database service from the PostgreSQL image on {product-title}.
+. Creating a frontend service from the Ruby 2.0 builder image on {product-title} and your Ruby on Rails source code, connected to the database service.
+. Creating a route for your application.
 
 .Procedure
 
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-* To deploy your Ruby on Rails application, create a new project for the application:
+* Create a project for your Rails application by running the following command:
 +
 [source,terminal]
 ----

modules/templates-rails-setting-up-database.adoc

@@ -5,18 +5,19 @@
 [id="templates-rails-setting-up-database_{context}"]
 = Setting up the database
 
-Rails applications are almost always used with a database. For local development use the PostgreSQL database.
+[role="_abstract"]
+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 {product-title}.
 
 .Procedure
 
-. Install the database:
+. Install the database by running the following command:
 +
 [source,terminal]
 ----
 $ sudo yum install -y postgresql postgresql-server postgresql-devel
 ----
 
-. Initialize the database:
+. Initialize the database by running the following command:
 +
 [source,terminal]
 ----
@@ -25,18 +26,21 @@ $ sudo postgresql-setup initdb
 +
 This command creates the `/var/lib/pgsql/data` directory, in which the data is stored.
 
-. Start the database:
+. Start the database by running the following command:
 +
 [source,terminal]
 ----
 $ sudo systemctl start postgresql.service
 ----
 
-. When the database is running, create your `rails` user:
+. When the database is running, create your `rails` user by running the following command:
 +
 [source,terminal]
 ----
 $ sudo -u postgres createuser -s rails
 ----
 +
-Note that the user created has no password.
+[NOTE]
+====
+The user that is created has no password.
+====