Arvados

I agree that the config documentation should be more convenient, but I disagree about recommending copying/customizing application.default.yml. If you do that, after a few code updates the local config file will contain a lot of convincing-looking, but outdated, documentation -- which can easily cause more trouble than the inconvenience of having to (and knowing that you have to) cross-reference a docs-and-defaults file.

Unfortunately I don't know what the silver bullet is here, either. If our upgrade procedure could automatically (and safely) update the comments in the local config file, that'd be great, but it also seems unlikely. Would it help to extend our "rake config:check" task to make a more human-readable report of {config, default setting, local setting, doc string}? It's not very interactive, but it could be done safely and reliably.

Reviewing 415ecc4.

• Can you explain to me what's going on with hardcoded_api_tokens.rb.example?
• Please remove the "Additional settings" section and merge the text into the text that's immediately under the heading "Configure the API server" as written in the description. This text already explains the relationship between application.yml and application.default.yml, so it's a good place to point out that documentation is available from the latter but changes should be made to the former.
• "Edit /etc/arvados/api/application.yml and to configure the settings described in the following sections." - remove one of "and to"
• "Only put local configuration in application.yml, do not edit application.default.yml." - This is two sentences. They should be separated with a period.
• I don't think we want to tell people to generate a random uuid_prefix. I think they can use whatever generation method they want, whether random or not. Did I miss a discussion somewhere?
• Every instance of the text "set it to application.yml:" should change "to" to "in."
• Under websockets_address:
  • There's text "Set websockets_address to the @wss:// URL" - that at-sign looks extraneous.
  • The example contradicts the text and gives an HTTPS URL. The text is correct; the example should use the WSS scheme.
• The paragraph describing git_internal_dir has an extra "is" in the first sentence, and the third sentence seems a little redundant with the first. What about, "The git_internal_dir setting specifies the location of Arvados' internal git repository. Arvados stores every git commit run in a Crunch job here. By default this is /var/lib/arvados/internal.git."
• Please restore the instructions to ensure a clone of the arvados repository lives under git_repositories_dir.

Thanks.