Feedback on installation guide

9 posts / 0 new
Last post
Feedback on installation guide
  • Are the backslash preceding $IPF_ETC and \$INSTALL_DIR intentional?  E.g.,

"IPF workflows are typically defined by JSON files under \$IPF_ETC/ipf/workflow/, particularly in \$IPF_ETC/ipf/workflow/glue2."

  • Sometimes $IPF_ETC is used and other times $IPF_ETC_PATH. Pick one.
  • In some cases, footnotes are used to reference external sites and other times, it is inlined as a hyperlink.  Seems like inlined would be easier for people to find unless you can make that footnote ref clickable.  Usually citations are in square brakets that's why it looked a bit funny to me.  E.g.,

"Before installing IPF operators should register their resource in RDR (4)."

"To install IPF on machines that are part of multiple XSEDE resources please first review XSEDE's Advanced Integration Options documentation."

  • In prerequisites, can you elaborate what is the minimal information that needs to be registered in RDR before installing IPF?  It's not obvious why it's a prerequisite and an SP may not have all the info as they are prepping a new resource to come online (e.g., various dates).
  • The "Preparing to Install IPF" section looks like Prerequisites to me.  I would move the content that section to be first under the "Pre-Requisites" section.   
  • I would also change this bullets as follows:

"Install and run IPF on a single server for each resource." to "Identify a single server to run IPF -- a single IPF instance can be used to publish information for multiple resources."

  • You need to describe the authentication options before this sentence. "If IPF will authenticate to Information Services using a X.509 host key/certificate..." , the public and private keys must be readable by the user running IPF." 
  • I think we should get rid of this sentence and any references to xdresourceid since we plan to retire it before the end of XSEDE.

"(Optional) The xdresourceid tool. If not available a resourceid will need to be configured by hand."

  • In the RPM section, you say "Note(s): - The RPM will automatically create an "xdinfo" account that will own the install and that will execute the workflows via sudo." but yet in the Pip section, you don't mention creating a user account.  In the Prerequisites section, you should probably add a bullet about deciding between Pip or RPM and the benefits/tradeoffs of one versus the other.
  • Under "Pre-configuration templates" section, the formatting looks a bit scrunched like it's missing newlines.  There's also repetitive text about how to find the site_packages dir.

 

Delivery Effort Stage: 

I've pushed changes removing the backslashes (which at some point I thought were needed to escape certain characters, but don't seem to be), and changing all IPF_ETC instances to IPF_ETC_PATH (which is the correct env variable.

You can see these changes at https://github.com/XSEDE/ipf/blob/xci-906/docs/INSTALL.md

 

I will address the other concerns, but wanted to note that these changes have been pushed.

I believe I have addressed the concerns listed above, and pushed to the XCI-906 branch, as viewable at https://github.com/XSEDE/ipf/blob/xci-906/docs/INSTALL.md

Hi Eric,

Thanks for the changes -- it looks like the following bullets still need to be addressed.  

  • In some cases, footnotes are used to reference external sites and other times, it is inlined as a hyperlink.  Seems like inlined would be easier for people to find unless you can make that footnote ref clickable.  Usually citations are in square brakets that's why it looked a bit funny to me.  E.g.,

"Before installing IPF operators should register their resource in RDR (4)."

"To install IPF on machines that are part of multiple XSEDE resources please first review XSEDE's Advanced Integration Options documentation."

  • In prerequisites, can you elaborate what is the minimal information that needs to be registered in RDR before installing IPF?  It's not obvious why it's a prerequisite and an SP may not have all the info as they are prepping a new resource to come online (e.g., various dates).

Thanks,
Shava

 

I've changed the prereq re: RDR to read:

 

-   Before installing IPF operators should register their resource in
    [RDR (4)](#RDR).  While IPF is capable of publishing information about resources
    that are not found in RDR, our intent here is to publish information about
    XSEDE resources, which should match/map to what is found in RDR.

 

I've also created internal links for each of the non-inlined references.

 

All changes can be seen at https://github.com/XSEDE/ipf/blob/xci-906/docs/INSTALL.md

Eric

Search for "python -c" and "$ ipf" (without the quotes) to find three example commands that need two blank lines in front of them to be properly formatted. Search for "-rpm" (without the quotes) to find the section where ipf_configure_xsede parameters are shown to start with a single hyphen or emdash instead of double hyphens. That section ends with "ipf_configure_xsede –help". Non-ASCII characters are troublesome here. On CentOS 8, with the python36 rpm installed, the command is "pip3" instead of "pip" (which dnf says is not provided by any rpm). Since Python 3 is required, always running "pip3" may be the most portable instruction.

Good catch on the em-dashes.  That was an artifact of importing and exporting from Google Docs when JP and I were both editing the install doc at the same time.

I've made these changes (including a sentence that explains "pip3".  Changes can be seen at:

https://github.com/XSEDE/ipf/blob/xci-906/docs/INSTALL.md

 

 

The INSTALL Guide doesn't mention the new "IPF_FLAGS: NOPUBLISH" module configuration feature.

I've added it to the section on adding fields to your module files.  

Log in to post comments