diff --git a/applications/creating_applications/templates-using-ruby-on-rails.adoc b/applications/creating_applications/templates-using-ruby-on-rails.adoc index 15260d01b3f..867962e8b96 100644 --- a/applications/creating_applications/templates-using-ruby-on-rails.adoc +++ b/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] diff --git a/modules/templates-rails-configuring-application.adoc b/modules/templates-rails-configuring-application.adoc index 6459954cccc..588beda0ee8 100644 --- a/modules/templates-rails-configuring-application.adoc +++ b/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 diff --git a/modules/templates-rails-creating-database-service.adoc b/modules/templates-rails-creating-database-service.adoc index e62a9d0213e..18a176fa5ac 100644 --- a/modules/templates-rails-creating-database-service.adoc +++ b/modules/templates-rails-creating-database-service.adoc @@ -5,15 +5,16 @@ [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. @@ -21,21 +22,19 @@ Setting these variables ensures: .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] ---- diff --git a/modules/templates-rails-creating-frontend-service.adoc b/modules/templates-rails-creating-frontend-service.adoc index ea0f0828dd8..18ccf5b6e90 100644 --- a/modules/templates-rails-creating-frontend-service.adoc +++ b/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--`, and that is your application running in {product-title}. +The output includes a line starting with `myapp--`, 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 ---- + -** 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. diff --git a/modules/templates-rails-creating-route-for-application.adoc b/modules/templates-rails-creating-route-for-application.adoc index 297964f26e6..2e30b433c0e 100644 --- a/modules/templates-rails-creating-route-for-application.adoc +++ b/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[] diff --git a/modules/templates-rails-creating-welcome-page.adoc b/modules/templates-rails-creating-welcome-page.adoc index c8396b28c2d..6bdd1a685fc 100644 --- a/modules/templates-rails-creating-welcome-page.adoc +++ b/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. diff --git a/modules/templates-rails-deploying-application.adoc b/modules/templates-rails-deploying-application.adoc index 260d9e444af..25b519a02be 100644 --- a/modules/templates-rails-deploying-application.adoc +++ b/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] ---- diff --git a/modules/templates-rails-setting-up-database.adoc b/modules/templates-rails-setting-up-database.adoc index ea7d6725f65..5a1d2f3e047 100644 --- a/modules/templates-rails-setting-up-database.adoc +++ b/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. +==== diff --git a/modules/templates-rails-storing-application-in-git.adoc b/modules/templates-rails-storing-application-in-git.adoc index 1c2051a03df..16154d8baa2 100644 --- a/modules/templates-rails-storing-application-in-git.adoc +++ b/modules/templates-rails-storing-application-in-git.adoc @@ -6,15 +6,16 @@ [id="templates-rails-storing-application-in-git_{context}"] = Storing your application in Git -Building an application in {product-title} usually requires that the source code be stored in a git repository, so you must install `git` if you do not already have it. +[role="_abstract"] +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 {product-title}. .Prerequisites -* Install git. +* You have installed Git. .Procedure -. Make sure you are in your Rails application directory by running the `ls -1` command. The output of the command should look like: +. Verify that you are in your Rails application directory by running the following command: + [source,terminal] ---- @@ -41,33 +42,37 @@ tmp vendor ---- -. Run the following commands in your Rails app directory to initialize and commit your code to git: +. Initialize a Git repository in your Rails application directory by running the following command: + [source,terminal] ---- $ git init ---- + +. Stage all application files by running the following command: + [source,terminal] ---- $ git add . ---- + +. Commit the staged files by running the following command: + [source,terminal] ---- $ 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. -. Set the remote that points to your `git` repository: +. Create a GitHub repository for your application. + +. Set the remote that points to your `git` repository by running the following command: + [source,terminal] ---- $ git remote add origin git@github.com:.git ---- -. Push your application to your remote git repository. +. Push your application to your remote Git repository by running the following command: + [source,terminal] ---- diff --git a/modules/templates-rails-writing-application.adoc b/modules/templates-rails-writing-application.adoc index 625318f57b3..29955504885 100644 --- a/modules/templates-rails-writing-application.adoc +++ b/modules/templates-rails-writing-application.adoc @@ -5,11 +5,12 @@ [id="templates-rails-writing-application_{context}"] = 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. +[role="_abstract"] +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: +. Install the Rails gem by running the following command: + [source,terminal] ---- @@ -23,37 +24,35 @@ Successfully installed rails-4.3.0 1 gem installed ---- -. After you install the Rails gem, create a new application with PostgreSQL as your database: +. Create a new application with PostgreSQL as your database by running the following command: + [source,terminal] ---- $ rails new rails-app --database=postgresql ---- -. Change into your new application directory: +. Change into your new application directory by running the following command: + [source,terminal] ---- $ cd rails-app ---- -. 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: +. 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: + [source,terminal] ---- gem 'pg' ---- -. Generate a new `Gemfile.lock` with all your dependencies: +. Generate a new `Gemfile.lock` with all your dependencies by running the following command: + [source,terminal] ---- $ bundle install ---- -. 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: +. Update the `default` section in the `config/database.yml` file to use the `postgresql` adapter, as shown in the following example: + [source,yaml] ---- @@ -66,11 +65,9 @@ default: &default password: ---- -. Create your application's development and test databases: +. Create the `development` and `test` databases for your application by running the following command: + [source,terminal] ---- $ rake db:create ---- -+ -This creates `development` and `test` database in your PostgreSQL server.