Passenger Ruby Report App Tutorial

Passenger Ruby Status App Tutorial

**Note: this is a DRAFT of a tutorial that will be moved to **

Passenger Overview

TODO

Tutorial: Overview of ps example app

We will be starting with an example status app that displays the output of the ps command:

screenshot

We will be modifying this app to instead display the formatted output of the quota command:

screenshot

Login to Open OnDemand, click "Develop" and "My Sandbox Apps (Development)". Click "New Product" and "Clone Existing App". We will create an app that displays the formatted output of the quota command.

screenshot

1. Directory name: quota
2. Git remote: https://github.com/OSC/ood-example-ps
3. Check "Create new Git Project from this?"
4. Click Submit

screenshot

Launch the app by clicking the large blue Launch button and in a new browser window/tab you will see the output of a ps command filtered using grep.

screeenshot

The features of this app include:

1. The app uses the custom branded Bootstrap 3 that My Jobs ande ActiveJobs apps use.
2. The navbar contains a link back to the dashboard.
3. On a request, the app runs a shell command, parses the output, and displays the result in a table.

This serves as a good starting point for any status app to build for OnDemand, because

1. the app has the branding matching other OnDemand apps
2. all status apps will do something similar on a request to the app:
   1. get raw data from a shell command or http request
   2. parse the raw data into an intermediate object representation
   3. use that intermediate object representation to display the data formatted as a table or graph

Go back to the Dashboard browser window/tab where the quota details page is displayed. Click the Files button to open this app in the File Explorer. Notice the structure of the app. It is a Ruby Passenger app that uses the Sinatra web framework:

1. config.ru is the entry point for the app (as is for all Ruby Passenger apps)
2. the Gemfile and Gemfile.lock specify the Ruby gem dependencies, and those dependencies are installed in vendor/bundle
3. public/ contains static css and js files. everything under public/ is automatically served up by NGINX
4. views/ contains index.html which is the template for the body of the index page, and the layout.html which contains the erb tag <%== yield %> that is replaced with the rendered contents of index.html

Select config.ru and click "Edit" to open in the File Editor app to view. Here is part of the config.ru file that defines a single route for '/':

get '/' do
  # Define your variables that will be sent to the view.
  @title = "Currently Running OnDemand Passenger Apps"
  @command = "ps aux | grep App | grep -v grep"

  # Run the command and capture the stdout, stderr, and exit code as separate variables.
  stdout_str, stderr_str, status = Open3.capture3(@command)

  # Parse the stdout of the command and set the resulting object array to a variable.
  @app_processes = parse_ps(stdout_str)

  # If there was an error performing the command, set it to an error variable.
  @error = stderr_str unless status.success?

  # Variables will be available in views/index.erb
  erb :index
end

This does 3 things:

1. Sets several instance variables for things like the title and the command to run
2. Executes a shell command, calls a helper method to parse the output, and sets the resulting array of structs to an instance variable
3. Renders the views/index.erb which makes uses of the instance variables to render the webpage

The parsing of the command's output is handled by a method that accepts a string and returns an array of structs. The struct has an attribute for each column of the command's output.

AppProcess = Struct.new(:user, :pid, :pct_cpu, :pct_mem, :vsz, :rss, :tty, :stat, :start, :time, :command)

helpers do
  def parse_ps(ps_string)
    ps_string.split("\n").map { |line| AppProcess.new(*(line.split(" ", 11)))  }
  end
end

The rendering of views/index.erb` is done using an alternative ERB implementation that by default escapes any HTML characters in the output of the ERB tags. `See erubi for details<https://github.com/jeremyevans/erubi>`_.The views/index.erb displays the command used:

<pre>
$ <%= @command %>
</pre>

And then creates an HTML table to display the results, iterating over the array of structs the parsing method created and creating one row for each struct:

<% @app_processes.each do |app| %>
<tr>
  <td><%= app.user %></td>
  <td><%= app.pid %></td>
  <td><%= app.pct_cpu %></td>
  <td><%= app.pct_mem %></td>
  <td><%= app.vsz %></td>
  <td><%= app.rss %></td>
  <td><%= app.tty %></td>
  <td><%= app.stat %></td>
  <td><%= app.start %></td>
  <td><%= app.time %></td>
  <td><%= app.command %></td>
</tr>
<% end %>

Tutorial: Creating a quota app from the ps app

1. Update the route "/" to execute the quota command:

   We use quota -spw because it will be easier to parse.

2. Replace the parse_ps method and AppProcess struct with parse_quota method and Volume struct:

3. Update views/index.erb to iterate over the Volume array and create table rows:

Go back to the dashboard in the details view of the quota app. Click "Restart App" to force Passenger to restart the app the next time you access it. Then click the blue launch button to open the app again in a new window.

FIXME: should we be showing an error and how to fix it? and then restart again?

Tutorial: Publishing the quota app

TODO

1. Finish explaining how the ps app works
2. Show what lines to change and how to restart the app to see the changes (so the functionality is working).
3. (bonus) Add sparklines js file to the project and then update the table to show this.
4. Update the manifest.yml for branding purposes, and explain how to see all of the Font Awesome icons
5. Show publishing an app, including specifying its category (which should appear in the app details, along with specifying whether this is in the navbar whitelist) and configuring the whitelist for a new navbar menu.