Special installation aspects (#358)

[Hooverdan96]

Fixes #358

This pull request's proposal

Add a section for commonly-used "special" aspects of Rockstor installations.

Checklist

• With the proposed changes no Sphinx errors or warnings are generated.
• I have added my name to the AUTHORS file, if required (descending alphabetical order).

[Hooverdan96]

I created a first draft based on the discussion in the associated Issue #358. @phillxnet, @FroggyFlox, take a look at what could be improved/changed/removed.

Failed link check instances are the usual suspects:

(interface/docker-based-rock-ons/plex-media-server: line   54) broken    https://ark.intel.com/ - 403 Client Error: Forbidden for url: https://ark.intel.com/
(interface/system/update_channels: line   16) broken    https://opensource.org/license/mit-0 - 403 Client Error: Forbidden for url: https://opensource.org/license/mit-0
(interface/system/update_channels: line   16) broken    https://opensource.org/license/apache-2-0 - 403 Client Error: Forbidden for url: https://opensource.org/license/apache-2-0

[Hooverdan96]

FYI, the linkcheck_ignore was updated for the three failures in another PR (#500) that's currently open.

[Hooverdan96]

Also, referencing #287 and see whether more/different info should be added to a static IP section.

[phillxnet]

@Hooverdan96 This is a nice addition, with lots of details. Thanks.

But for me this is entirely miss-placed in our generic installer-howto. It pertains to likely less than 1% of users, and looks super scary to the 99% who will look at this doc, hopefully scrolling through to see what they may encounter. Viewing this last section would put me off. We are, up to this point. Super simple. I'm strongly against this addition in this how-to. But the contents is great for folks who are CLI happy with advanced requirements. Not 99% of installer users as I see it. Otherwise they would not be using a Web-UI NAS setup but hand-crafting their own non-limited configurations on a linux base of their choice.

How about this same contents is put in it's own how-to: and we have a note at the end of the installer doc that in-turn links to this new Special Installation Scenarios, with the note highlighting that the vast majority of users will not need to reference the 'Special'.

We absolutely must keep our existing how-to as short as possible. And entirely void of this type of off-putting detail; was my thinking. I.e. akin to @FroggyFlox moving my prior downloads page instructions on installing the rpms on vanilla openSUSE:

https://rockstor.com/docs/howtos/rpm_install.html

I crammed in details on the download page, where-as they deserved their own how-to.
I think similarly about this highly advanced extension to our installer how-to.

So in-brief I don't think this belongs in the generic installer how-to as it does not pertain to our installer: but to advanced setup pertaining to a an extreme minority of users. Ergo we have a single paragraph note at most referencing this content but in its own how-to. Folks can then reference that doc if need-be. Keeping the existing how-to focused to our installer and how to use it. Not all possible variations of what configuration may pertain to niche and in some cases with this additional info unsupported installs (VM/hypervisor host).

Lets see what it looks like in its own how-to: with a single paragraph note leading to it from the installer. Where that note indicates why you may need to click on the 'Special ...'. But little else. We absolutely must not grow this base installer how-to more than is absolutely necessary was my thinking here.

However: the write-up of what you've addressed is, as is normal for you, excellent :) .

What do your think? Are you OK moving this to its own how-to? We could have that how-to listed right next to this installer: if that helps to group stuff together. And as it also pertains to actually installing, possibly next to our existing:

Install on Vanilla openSUSE/SuSE SLES

I.e. while there we could have our installer-howto also added to the how-to entries: resulting in for example:

• Rockstor’s “Built on openSUSE” installer (not moved, just added as a how-to link)
• Special Installation Scenarios (your advanced/unsupported options/notes presented here)
• Install on Vanilla openSUSE/SuSE SLES (@FroggyFlox advancement/abstraction on my original downloads page bloat).

That way we are helping to group together progressively more advanced install doc entries. Where the first servers the vast majority, but all can easily lead into the more advanced option as needed.

[Hooverdan96]

@phillxnet, @FroggyFlox: take a look at this. After rebasing, I broke out the special install scenarios. I also took your "hint" in #506 to adjust the text to semantic linefeeds within the documents I touched.

[phillxnet]

@Hooverdan96 This is now looking much nicer, thanks.

I've made a few suggestions re wording etc. See what you think.

I know the repositioning/abstraction causes an anomaly regarding doc continuity; but I think it is far better this way and the docs is random-access after all. Although hopefully not entirely randomly read :). I'm referencing here our before and after footer links. As-is I think they have worked out OK: defaulting as they did with my build here at least to their original position re the installer. Our how-tos are only vaguely ordered. And you placement of the 'special' install into our installer section looks to work also: nice.

Thanks also for embarking on the semantic line-feeds.
It can really help with reviewing smaller changes there-after.

[phillxnet]

@Hooverdan96 Thanks for applying the requested changes. Can I now look to this again, i.e. are you done with the changes?

Thanks for this monster recent docs effort by the way. Much appreciated. And my apologies to taking so long to track all your changes :) .

[Hooverdan96]

you're very welcome, and no worries on it taking more time, you do have a life :).

Yes, you can review the changes now.

[phillxnet]

@Hooverdan96 Thanks for what is a definite improvement in installer doc coverage. And for accommodating my suggestions re rearrangements.

All looks dandy now so I'll merge a get to publishing shortly.

[phillxnet]

PR product PRODUCTION published.