Bug #17591

Improve explanation of wildcard DNS for keep-web

Added by Peter Amstutz 5 months ago. Updated 23 days ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Target version:
Start date:
08/03/2021
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
-
Release relationship:
Auto

Description

DNS entries and TLS certificates section of "planning and prerequisites" in the install guide needs to be more specific and precise.

Also noted: talks about hostnames but these are usually virtual hosts.

This section should tell you (a) what certificates to get and (b) what DNS hosts to set up.


Subtasks

Task #17671: ReviewResolvedWard Vandewege

Associated revisions

Revision 76b03c65
Added by Ward Vandewege about 2 months ago

Merge branch '17591-doc-improvement'

closes #17591

Arvados-DCO-1.1-Signed-off-by: Ward Vandewege <>

History

#1 Updated by Peter Amstutz 5 months ago

  • Target version changed from 2021-05-12 sprint to 2021-05-26 sprint

#2 Updated by Peter Amstutz 4 months ago

  • Description updated (diff)

#3 Updated by Peter Amstutz 4 months ago

  • Description updated (diff)

#4 Updated by Peter Amstutz 4 months ago

  • Description updated (diff)

#5 Updated by Peter Amstutz 4 months ago

  • Assigned To set to Nico César

#6 Updated by Peter Amstutz 4 months ago

  • Target version changed from 2021-05-26 sprint to 2021-06-09 sprint

#7 Updated by Peter Amstutz 3 months ago

  • Target version changed from 2021-06-09 sprint to 2021-06-23 sprint

#8 Updated by Peter Amstutz 3 months ago

  • Target version changed from 2021-06-23 sprint to 2021-07-07 sprint

#9 Updated by Peter Amstutz 2 months ago

  • Target version changed from 2021-07-07 sprint to 2021-07-21 sprint

#10 Updated by Peter Amstutz about 2 months ago

  • Assigned To deleted (Nico César)

#11 Updated by Peter Amstutz about 2 months ago

  • Target version changed from 2021-07-21 sprint to 2021-08-04 sprint

#12 Updated by Peter Amstutz about 2 months ago

  • Assigned To set to Ward Vandewege

#13 Updated by Ward Vandewege about 2 months ago

  • Status changed from New to In Progress

#14 Updated by Ward Vandewege about 2 months ago

Ready for review at 6160b7425d9da6cc9d245b7cc754e81427f8ac9c on branch 17591-doc-improvement

#15 Updated by Tom Clegg about 2 months ago

I think the new "if you have this then do that" table is a huge improvement.

I noticed a (pre-existing) missing "the" in doc/install/install-manual-prerequisites.html.textile.liquid: "You can run several services on same node, but ..."

Re note in description "talks about hostnames but these are usually virtual hosts"... would it be more clear to say "DNS name" instead of "hostname" when referring to a name in a URL as opposed to the thing reported by the hostname command? E.g., in "each distinct hostname requires a valid, matching TLS certificate" we could say "each distinct DNS name"?

I suspect in many cases wildcard TLS and DNS are possible, but require extra effort, and people will be inclined to avoid the extra effort by going with the "other" column, even though the text assures them it will be "easier" with wildcards. Should we mention here that skipping the wildcards will have consequences later ("this will disable some features that allow users to view Arvados-hosted data in their browsers" or something like that?), rather than let people think they're taking the easy route only to find out later that they need to come back and reconfigure.

#16 Updated by Ward Vandewege about 2 months ago

Tom Clegg wrote:

I think the new "if you have this then do that" table is a huge improvement.

I noticed a (pre-existing) missing "the" in doc/install/install-manual-prerequisites.html.textile.liquid: "You can run several services on same node, but ..."

Fixed!

Re note in description "talks about hostnames but these are usually virtual hosts"... would it be more clear to say "DNS name" instead of "hostname" when referring to a name in a URL as opposed to the thing reported by the hostname command? E.g., in "each distinct hostname requires a valid, matching TLS certificate" we could say "each distinct DNS name"?

OK, changed.

I suspect in many cases wildcard TLS and DNS are possible, but require extra effort, and people will be inclined to avoid the extra effort by going with the "other" column, even though the text assures them it will be "easier" with wildcards. Should we mention here that skipping the wildcards will have consequences later ("this will disable some features that allow users to view Arvados-hosted data in their browsers" or something like that?), rather than let people think they're taking the easy route only to find out later that they need to come back and reconfigure.

Yeah, good idea, I've added some language like that.

I've also made an explicit mention of the 'TrustAllContent' flag on the keep-web urls page, and fixed the explanation for that flag in the default config file, it was missing a word.

Ready for another look at 1c5a21a73b2e5281cea17db4ae5f4d367dee1ee4

#17 Updated by Tom Clegg about 2 months ago

LGTM, thanks!

#18 Updated by Ward Vandewege about 2 months ago

  • % Done changed from 0 to 100
  • Status changed from In Progress to Resolved

#19 Updated by Peter Amstutz 23 days ago

  • Release set to 41

Also available in: Atom PDF