Bug #7129

[Documentation] RVM and passenger recipes are missing details

Added by Tom Clegg over 3 years ago. Updated over 3 years ago.

Status:
New
Priority:
Normal
Assigned To:
-
Category:
Documentation
Target version:
Start date:
08/25/2015
Due date:
% Done:

0%

Estimated time:
Story points:
0.5

Description

While reviewing #6940 I ran into a couple of hiccups:
  1. I have to yum install curl which tar in order to get the RVM installer to the point where it could install the rest by itself. (Debian comes with which and tar, but still needs apt-get install curl in the RVM recipe.)
  2. The "Install Nginx and Phusion Passenger" link takes me to a page that says "This is the old, deprecated Passenger for Nginx documentation" and whether I try to follow it anyway or go to the "new docs", I end up having to make a bunch of decisions that seem to depart from "follow-the-recipe" mode. Even when I stop pretending to be a newcomer, I still find it hard to guess which Passenger recipe(s) the install guide really expects me to follow, and take a couple of wrong turns before I find the right path. I think we should provide more clues about the right path. I doubt we need this level of detail, but FTR the path I followed (successfully) was:
    • Follow link to current docs https://www.phusionpassenger.com/library/
    • Click Deployment button
    • Select Ruby icon and click Continue
    • Click "Any hosting provider or infrastructure running Linux/Unix ยป"
    • Select Nginx icon and click Continue
    • Select Passenger Open Source icon and click Continue
    • Skip the prerequisites and RVM/bundler stuff because I already did that (assuming I chose the RVM option, at least)
    • Install node.js (even though I suspect I don't need it because the assets should already be built in the package)
    • Click "Continue: install passenger"
    • Choose OS and version, click Continue
    • Install Passenger packages as instructed, uncomment stuff in configs as instructed
      • ...ignoring the fact that my passenger.conf says "passenger_root /usr/lib/ruby/1.8/phusion_passenger/locations.ini" because I know that's going to be overridden in my server config
    • Click "Continue: deploy app"
    • Realize this is probably where I should stop and go back to the Arvados install guide

One future hiccup:

"This will install and check your configuration, and install necessary gems" seems to be the only hint (disguised as a copy-and-paste error) that changing /etc/arvados/workbench/application.yml doesn't take effect until you run /usr/local/bin/arvados-workbench-upgrade.sh, which is not something anyone should be expected to guess. Until/unless we fix this weirdness, I think we need to draw attention to it explicitly. "How is it not reloading my new config even if I kill and restart the server process??" is the sort of thing it's really frustrating to figure out by trial and error, and invariably happens when you're trying to fix some other problem: change config vars; restart server; "nope, that didn't fix it"; repeat... (Is there even a reason we have to copy this instead of symlinking?)

Also one thing that doesn't qualify as a hiccup, just a mystery:

The nginx config seems unnecessarily complicated. I assume the idea is that you could take the proxy part to a different VM: we're effectively documenting "ssl proxy on same host" and "ssl proxy on different host" at the same time. Or does it actually not work to add the SSL configs directly to the Workbench server section? Perhaps Workbench relies on the headers that can only be added by a separate Proxy section? Either way perhaps it deserves a short comment -- even if the precise explanation is too obscure for this context, we can say "we recommend using a separate proxy section, even if the proxy and application are served by the same Nginx process."

History

#1 Updated by Tom Clegg over 3 years ago

  • Description updated (diff)

#2 Updated by Brett Smith over 3 years ago

Some changes to help improve the various problems here have already been made; e.g., the link has been updated to current Passenger documentation. The main thing this story calls for that we're still missing is some kind of indication of where you should stop following the Passenger documentation, and come back to the Arvados install guide. That needs to be added.

Also available in: Atom PDF