Arvados

Knocking down because the PostgreSQL bits are being done in #6499.

Comments on 5ac198c8. I started a Docker container from debian:jessie and followed instructions from there. Issues I discovered:

• It's not possible to carry out some of the instructions to set up authentication (e.g., create a local user) before a database is set up. Instructions to set up the database should move above instructions to set up an authentication method, and it might flow better to move them above instructions to set up application.yml.
• Currently the database instructions explain the production/development difference after they edit database.yml. That explanation should probably move above the editing command, so the user can be instructed to edit the corresponding section of database.yml.
• The provided command su postgres createdb arvados_sso_production -E UTF8 -O arvados_sso is malformed and doesn't run. su doesn't like that call syntax, and createdb needs to specify the database template with -T template0. It should be edited to use the same line in the API server instructions, with just the database names changed.
• The section "Run a standalone passenger server" misrenders in my browser. It looks like some kind of markup hiccup. See attached screenshot.
• We run SSO inside a dedicated Web server in production, so we should probably recommend the same nginx+Passenger setup we do for API server and Workbench, for symmetry and per the story description. (All our other guides give people instructions to make sure the thing runs as a daemon. The one-shot Passenger command here doesn't meet the same bar.) I figure I need to write that up, since it's undocumented otherwise?
• Maybe I'm testing it wrong, but if I naively visit the Passenger server directly, I ultimately end up at /users/sign_in with this error in my browser:
  

  Error compiling CSS asset
  
  Sass::SyntaxError: File to import not found on unreadable: bootstrap.
  Load path: /root/sso-devise-omniauth-provider
    (in /root/sso-devise-omniauth-provider/app/assets/stylesheets/application.css.scss)
  
    /root/sso-devise-omniauth-provider/app/assets/stylesheets/application.css.scss:10
  

Thanks.

Reviewing 8e74a5f. Most of this is just little grammar stuff, and I know you're not responsible for some of it, but given the scope of the story I'm mostly reading the generated HTML more than the diff.

• Is _install_tools expected to be shared with any other pages? (API server and Workbench share the Ruby include; and API server shares PostgreSQL.) Each page tends to have a special snowflake list of needed tools to install, so I'm not sure I see the value in abstracting this out. At the very least, "tools" seems like it's not descriptive enough of a name for the set of packages being suggested.
• "The config/application.yml.example file is not read by the SSO server and is provided for installation convenience, only." - The last comma in this sentence is extraneous.
• "It must be exactly 5 alphanumeric characters (lowercase ASCII letters and digits)." - It seems confusing to say "alphanumeric characters," then describe a different character class in parentheses. I think this should just say "5 lowercase ASCII letters and/or digits."
• "set in in Setting up Omniauth in the API server."
  • Please fix the double "in in"
  • With our new SSO configuration method, perhaps the link would read better as "the API server's SSO settings," or something like that? I'm not 100% sure myself, just a thought, take it or leave it. At least lowercase "Setting" since it no longer refers to a specific section title, please.
• In the list of steps to set up Google+ authentication:
  • The instructions interchangably use quotes and bold for things you should look for, and things you should click. They should at least be consistent between those two cases. I think using bold for both cases would be most consistent with the rest of our documentation, following the typography conventions in the user guide.
  • All list items should end with a period, since they're all sentences.
• "Note, if you get the following warning…" - The comma here should be a colon.
• When I tested following the instructions, I got this exception in the console after logging in (apparently successfully, so that's cool). If fixing this is a separate development story, we can make that story and declare it out of scope for this branch, but if it's a configuration oversight we should probably add that to the docs:
  

  Started GET "/" for 172.17.42.1 at 2015-07-30 19:50:10 +0000
  Processing by AuthController#welcome as HTML
    Rendered auth/welcome.html.erb within layouts/application (0.4ms)
    Rendered application/_links.html.erb (33.5ms)
  Completed 500 Internal Server Error in 38ms
  
  ActionView::Template::Error (undefined method `edit_user_registration_path' for #<#<Class:0x0000000399f950>:0x00000003986770>):
      2: <%- if current_user %>
      3:   <%= link_to "Sign out", :destroy_user_session, class: "btn btn-default btn-links", role: "button" %>
      4:   <%- if controller_name != 'registrations' %>
      5:     <%= link_to "Update account", :edit_user_registration, class: "btn btn-default btn-links", role: "button" %>
      6:   <% end %>
      7: <% end -%>
      8:
    app/views/application/_links.html.erb:5:in `_app_views_application__links_html_erb__628821696915024076_37371700'
    app/views/layouts/application.html.erb:34:in `_app_views_layouts_application_html_erb__3942301839687843190_37846480'
  

If these suggestions just lead to expected changes, go ahead and merge the branch, then assign this story to me to finish the nginx documentation follow-up. Thanks.

Applied in changeset arvados|commit:434be0f7e6420fee1b99e78466ee4a4d734734c1.