Metacat Documentation Update 3.0.0

[doulikecookiedough]

The documentation for Metacat Administrator's Guide has quite a few references to features that are no longer supported, deprecated and/or obsolete. This issue is to assist in helping to keep track of the updates and changes for the documentation, and includes the todos outlined here in Issue-1678: Remove/update Documentation Referencing Features to be Removed in v3.0.0)

Sections to review & update:

• [x] 1. Introduction intro.rst
• [ ] 2. Contributors contributors.rst
  • [x] Pending review
• [ ] 3. License license.rst
  • [x] Update to Apache 2.0 License, remove all references... everywhere.
  • [x] Pending review
• [ ] 4. Downloading & Installing Metacat install.rst
  • [x] Add section regarding RabbitMQ
  • [x] Pending review
• [ ] 5. Configuration configuration.rst
  • [x] Document token configuration (see additions on properties admin page for Token Verification Certificates and Admin Token Path
  • [x] Pending review
• [ ] 6. DataONE dataone.rst
  • [x] Pending review
• [x] 7. Submitting Metadata and Data submitting.rst
• [ ] 8. Metacat Indexing query-index.rst
  • [x] Document new reindex call
  • [x] Pending review
• [ ] 9. Modifying and Creating Themes themes.rst
  • [x] Pending review
• [x] 10. Metacat Authentication authinterface.rst
• [x] 11. OAI Protocol for Metadata Harvesting oaipmh.rst
• [x] 12. Event Logging event-logging.rst
  • Reviewed, no changes required.
• [x] 13. Enabling Web Searches: SiteMaps sitemaps.rst
  • [x] Pending Review
• [x] 14 Appendix: Metacat Properties metacat-properties.rst
  • [x] Pending Review
• [x] 15. Appendix: Development Issues development.rst
  • The sections here relate to development work in progress or in planning - and does not require changes at this time (other than for updates, such as the changes to HashStore)

New Chapters:

• [ ] Kubernetes Metacat Installation & Configuration
  • [x] Pending review
• [ ] Admin API Section
  • [x] Pending review
  • PUT /index See comment
  • PUT /identifiers See comment

Other:

• [x] Add documentation regarding changes to properties (using delimiters, Issue-1843):
  • event.log.blacklist.ipaddress -> event.log.deny.ipaddress
  • event.log.blacklist.subject -> event.log.deny.subject
  • These are properties that ESS-DIVE utilizes and we don't want to catch them by surprise
  • [x] Documented in metacat-properties.rst & Jing will email ESS-DIVE to give them a heads up
• [x] Add note about authentication mechanism

  If ORCID authentication is not suitable for your deployment, a custom authentication mechanism
  can be built. Metacat is written such that this Authentication provider is replaceable with
  another class that implements the same interface (``AuthInterface``). As an Administrator, you have
  the choice to provide an alternative implementation of ``AuthInterface`` and then configuring
  **metacat-site.properties** to use that class for authentication instead of ORCID authentication.

  • Added to authinterface.rst
• [x] Delete Harvester and Harvest List Editor harvester.rst (obsolete)
• [x] Delete replication doc replication.rst (obsolete)
• [x] Remove skin references (feature is deprecated/obsolete)

• [x] Add documentation for upgrades with solr

  We should mention in documentation, we must run solr under JAVA 1.8 during the upgrade (solrconfig.xml in Metacat 2.19.0 doesn't like JAVA 17). When the upgrade is done, we can switch to JAVA 17 for solr. Note: Tomcat should be running JAVA 17 during the upgrade process.

  We need add some documentation for solr 9.5: In solr 9.5, it doesn't like the wild card * setting in solr.bin.sh: SOLR_OPTS="$SOLR_OPTS -Dsolr.allowPaths=*" You should specify the exact path. Also it should NOT be a link path, it should be the real path: SOLR_OPTS="$SOLR_OPTS -Dsolr.allowPaths=/private/var/metacat" The solr_home property should be the real path as well.

• [x] In the top nav-bar, right side: Either fix the Index functionality (preferred if easy), or remove the Index link, since the index currently shows only 3 entries

[doulikecookiedough]

Progress Update on feature-1678-doc-updates

RE: intro.rst

• Removed references to obsolete/deprecated features, and reworded relevant sections.
• Added new metacatui home screenshot

RE: harvester.rst & oaipmh.rst

• A note/deprecated directive has been added to the top for the Harvesting & OAI-PMH sections.

RE: authinterface.rst

• Has been updated with instructions to use ORCID authentication.
• Removed LDAP/Password-based references

RE: submitting.rst

• Removed previous content and replaced with references to use metacatui or the DataONE REST API

RE: replication.rst

• Deleted

[doulikecookiedough]

Progress update on feature-1678-doc-updates2

• Added and revised some css styles in metacatui.css to improve how the docs are displayed

• Removed the 'index' option in the upper righthand corner (so it's only next, and previous now) (modified layout.html)

• RE: contributors.rst

  • Updated this section to match the new 3.0.0 README.md

• RE: install.rst

  • Added rabbitmq sections, and updated solr section with upgrade notes to 3.0.0
  • Added recommendations for solr 9.5.0, tomcat9 and postgres14.
  • Added Upgradting to Metacat 3.0.0 underneath Upgrade Metacat section
  • Formatted the document's usage of spacing so that it's consistent all throughout
  • Updated screenshots, fixed typos and slightly revised wording here and there

• RE: themes.rst

  • Removed skins references

• RE: dataone.rst

  • Removed deprecated section on replication (obsolete)
  • Fixed typos, updated screenshot

[doulikecookiedough]

Progress update on feature-1678-doc-updates3

RE: configuration.rst

• Added new sections for auth token and token verification certificate
• Updated outdated screenshots, deleted obsolete sections (ex. LSID-related references)
• Improved consistency in formatting/sectioning and revised wording

RE: readonly.rst

• Removed content related to deprecated and old Metacat API
• Note: This doc is referenced in configuration.rst

RE: event-logging.rst

• Reviewed, no changes required

RE: site-maps.rst

• Revised formatting

RE: query-index.rst

• Added new 'reindex' call
• Revised formatting

RE: auth-interface.rst

• Added section for custom authentication mechanism

RE: Appendix: Metacat Properties metacat-properties.rst

• Added ESS-DIVE specific hand-edited properties for reference purposes

RE: Appendix: Development Issues development.rst

• Reviewed, does not require changes at this time.

[doulikecookiedough]

Progress update:

Added to feature-1678-doc-updates3

• RE: kubernetes.rst
  • Add new doc with a sentence saying that a step-by-step guide will be added
• RE: admin-api.rst
  • Contains the admin api rest calls for PUT /identifiers and PUT /index

RE: Licenses

• Updated to Apache 2.0 License, PR created

[doulikecookiedough]

This issue has been addressed via:

• Feature-1678: Doc Updates Part 3
• Feature-1678: Doc Updates Part 2
• Feature-1678: Doc Updates Part 1