Port an existing app to OOD

Summary

Update to AweSim Appkit 1.0

To transition your app to the OOD infrastructure, your app must be compatible with the AweSim appkit v1.0.

To upgrade to the AweSim appkit v1.0, please see the guide.

Update Rails 4.0.13 and other gems to work with Ruby 2.2

Due to changes in the OOD gems, OOD applications will need to have a minimum Rails version of 4.0.13, you can also update to the latest version of Rails 4.2. Rails 5.0 is not yet supported.

We will be replacing the awesim_rails gem with the ood_appkit gem, and updating the rest of the OOD dependencies to work with the latest version of OodAppkit.

Steps

1. Clone the existing app to a directory under `/awesim/dev`

Do this through the dashboard web UI or via the shell on apps-test.awesim.org.

2. Update the `Gemfile`

Make these changes to your Gemfile (ignore osc-vnc and redcarpet if they are not in your Gemfile already):

-gem 'rails', '4.0.0'
+gem 'rails', '4.0.13'

-gem 'sass-rails', '~> 4.0.0'
+gem 'sass-rails', '4.0.2'
-gem 'bootstrap-sass', '~> 3.3.1'
+gem 'bootstrap-sass', '3.3.1.0'

-gem 'osc-machete', '~> 1.0.0'
-gem 'osc_machete_rails', '~> 1.0.0'
-gem 'osc-vnc', '~> 1.0.0'
+gem 'osc-machete', '~> 1.2.0'
+gem 'osc_machete_rails', '~> 1.2.0'
+gem 'osc-vnc', '~> 1.1.0'

-gem 'redcarpet', '~> 3.2.2'
+gem 'redcarpet', '~> 3.3.0'

-gem 'dotenv-rails', '~> 2.0.0'
+gem 'dotenv-rails', '~> 2.1', require: 'dotenv/rails-now'

-gem 'awesim_rails', '~> 1.0.0'
-# gem 'awesim_rails', path: '/nfs/17/efranz/dev/awesim_rails'
-gem 'awesim_rails_logging', '~> 1.0.0'
+gem 'awesim_branding', :git => 'git@github.com:AweSim-OSC/awesim_branding.git', :tag => 'v1.0.0'

make sure to include require: 'dotenv/rails-now for the dotenv gem so that environment variables are set properly when running rake tasks; this is now important for app sharing as we include RAILS_RELATIVE_URL_ROOT in the dotenv file
the osc-machete and osc_machete_rails gems are now on rubygems.org
awesim_branding is a replacement for awesim_rails and adds ood_appkit as a dependency
we remove awesim_rails and awesim_rails_logging gems, these are not supported on OOD

3. Replace references to `AwesimRails` with `OodAppkit`

i.e. AwesimRails.dataroot is replaced by OodAppkit.dataroot. The easy way to do this is run these two commands and the do a git status to review the changes:

grep AwesimRails app -Rl | xargs sed -i 's/AwesimRails/OodAppkit/g'
grep AwesimRails config -Rl | xargs sed -i 's/AwesimRails/OodAppkit/g'

In Container Fill Sim, here is an example commit: https://github.com/AweSim-OSC/containerfillsim/pull/64/commits/5ee2a9f9289eccdc89782fa2d2cbd93dfa5d2bdd

4. Delete `Gemfile.lock` and run bundler, and setup database

After completing these steps, delete the Gemfile.lock file and run bundle install from the dashboard web app or run this command:

scl enable rh-ruby22 nodejs010 -- bin/bundle install --path=vendor/bundle

Then setup the database again:

scl enable rh-ruby22 nodejs010 -- bin/rake db:setup

Now you should be able to access your app and test.

5. Explicitly update status of jobs on each request

In v1.0.0 of osc_machete_rails we tried to auto-update the active jobs of all Statusable subclass instances. This hasn't worked reliably and will be removed in a future release. To undo this change:

Add config/initializers/osc_machete_rails.rb

+OscMacheteRails.update_status_of_all_active_jobs_on_each_request = false


2. For each simulations controller add a before action and a method to update the active jobs:

    ```diff
class SimulationsController < ApplicationController
  before_action :set_simulation, only: [:show, :edit, :update, :destroy, :submit, :copy]
+  before_action :update_jobs, only: [:index, :show]

...

+  def update_jobs
+    SimulationJob.active.to_a.each(&:update_status!)
+  end
end

To ensure that update_jobs is called prior to the @simulation object being created, get rid of the before_action :set_simulation and call this explicitly in each controller action:

class SimulationsController < ApplicationController
- before_action :set_simulation, only: [:show, :edit, :update, :destroy, :submit, :copy]
  before_action :update_jobs, only: [:index, :show]

...
  def show
+   set_simulation
  end

...

  def edit
+   set_simulation
  end

...

  def update
+   set_simulation
    respond_to do |format|
...
  def destroy
+   set_simulation
    respond_to do |format|
...
  def submit
+   set_simulation
    respond_to do |format|
...
  def copy
+   set_simulation
    @simulation = @simulation.copy

6. Follow directions on app sharing

App sharing's setup setup now requires adding files that should be versioned with the app: https://github.com/AweSim-OSC/documentation/wiki/Sharing-apps-in-OOD#setup

Also, adding icons and manifest changes for app sharing are also documented https://github.com/AweSim-OSC/documentation/wiki/Sharing-apps-in-OOD

Diff Guide to removing the `awesim_branding` gem.

The AwesimBranding gem contains helper methods that were available in AwesimRails. These helpers have been deprecated and are replaced by similar functionality in the OodAppkit gem. The AwesimBranding gem allows for a smooth transition of existing applications to our OOD infrastructure, but ongoing support is limited and you are encouraged to update to OodAppkit.

Remove the `awesim_branding` gem

-gem 'awesim_branding', :git => 'git@github.com:AweSim-OSC/awesim_branding.git', :tag => 'v1.0.0'

Update `app/assets/stylesheets/application.css.scss`

-@import "awesim";
+
+// this MUST occur before you import bootstrap
+@import "ood_appkit/bootstrap-overrides";
 
 // Load up bootstrap style sheet
 @import "bootstrap";
 
-// display header at top of app layout
-body {
-  @extend .awesim-banner-background-img;
-}
-
+// this MUST occur after the bootstrap import
+@import "ood_appkit";

Update `app/views/layouts/application.html.erb`

Remove the `awesim_banner`

<body>
 
-<%= awesim_banner "Container Fill", "SIM" %>
-
 <header>

Replace `awesim_breadcrumbs` with OodAppkit navbar breadcrumbs

-  <nav class="navbar navbar-inverse navbar-static-top" role="navigation">
+  <nav class="ood-appkit navbar navbar-inverse navbar-static-top" role="navigation">
     <div class="container-fluid">
       <!-- Brand and toggle get grouped for better mobile display -->
       <div class="navbar-header">
         . . . .         
         </button>
-        <%= awesim_breadcrumbs 'Container Fill Sim' %>
+        <ul class="navbar-breadcrumbs">
+          <li><%= link_to OodAppkit.dashboard.title, OodAppkit.dashboard.url.to_s %></li>
+          <li><%= link_to 'Container Fill Sim', root_path %></li>
+        </ul>
       </div>

Replace the `docs_path` with `wiki_path`

If you have documentation in a /docs folder, rename it to /wiki
Change docs_home to wiki_home:

<%= link_to "Tutorial", docs_path('Home') %>

<%= link_to "Tutorial", wiki_path('Home') %>


    * you can do this by running the command `grep docs_path app -Rl | xargs sed -i 's/docs_path/wiki_path/g'`

3. change the gitignore to hide /wiki instead of /docs

        sed -i 's/\/docs/\/wiki/g' .gitignore


In Container Fill Sim, here is an example commit: https://github.com/AweSim-OSC/containerfillsim/pull/64/commits/e48f1bfcb4f1af5e4f97e05843523e14789f236b

Further information at [OodAppkit](https://github.com/OSC/ood_appkit/)

Summary

Update to AweSim Appkit 1.0

Update Rails 4.0.13 and other gems to work with Ruby 2.2

Steps

1. Clone the existing app to a directory under /awesim/dev

2. Update the Gemfile

3. Replace references to AwesimRails with OodAppkit

4. Delete Gemfile.lock and run bundler, and setup database

5. Explicitly update status of jobs on each request

6. Follow directions on app sharing

Diff Guide to removing the awesim_branding gem.

Remove the awesim_branding gem

Update app/assets/stylesheets/application.css.scss

Update app/views/layouts/application.html.erb

Remove the awesim_banner

Replace awesim_breadcrumbs with OodAppkit navbar breadcrumbs

Replace the docs_path with wiki_path