The Hyrax Guide

This repository builds documentation for the official Hyrax Guide, OPeNDAP's data server.

This manual describes the features and operation of the Hyrax data server, a data server developed by OPeNDAP, Inc. as a reference server for the Data Access Protocol, versions 2 and 4. the Hyrax server is modular software with a number of handlers that are loaded into a core framework based on the contents of configuration files. Each of the server’s modules provides a distinct functional capability, such as reading data from a certain kind of file, encoding data, or processing data in different ways.

How to Contribute

The documentation is built automatically from the source AsciiDoc files (*.adoc). To propose any change you need to create a new branch, and submit a PR with the proposed changes for review. Before submitting a new PR, we suggest to tryout to build the documentation on a local machine. Thus the minimal requirements are:

• Clone the Repository
• Install AsciiDoctor on your workstation (test purposes).

Instructions

• Optional: Navigate to the root directory. Master_Hyrax_Guide.adoc should be there.
• Make changes (using a new branch - do not commit on main).
• Test the proposed changes by running on the command line

asciidoctor -a toc=left -a docinfo=shared Master_Hyrax_Guide.adoc

NOTE: In some cases there may be some errors during the build (unrelated to the new changes). Verify your changes were added correctly:

• The command above should generate a new file Master_Hyrax_Guide.html. You can inspect it with a brower, e.g. open DAP4.html.
• Add and commit the new changes, and push to Request a Pull Request review. Once approved, the changes should be published automatically by Travis.

Notes about the meta-documentation files

Added jhrg 9/17/17

• Use ---- for the delimeters for source code
• Use .... for the delimeters for litteral text like shell input
• Use [source,xml] as a prefix to the source blocks (change language as needed). See info about coderay (http://coderay.rubychan.de/) for the allowed set.

Notes about specific adoc files

preface.adoc

If we use the book format, we can have a preface and should move the acknowledgements from Hyrax.adoc to there (I think) along with other text like, this is why Hyrax exists and/or other stuff that one usually finds in a Preface.

Master_Hyrax_Guide.adoc

This is the main document for the whole manual. It now uses include directives in place of _link_s. There are notes in the file about building the manual as a multipart book. There other notes about missing content sections (like how to install the BES or start the OLFS).

I changed the title to The Hyrax Data Server Installation and Configuration Guide and it now has six sections (Overview, Installation, Configuration, Operation, Security, and Troubleshooting) and four appendices (WMS, handlers, Aggregation, and Server side processing).

Issues:

• Are these the correct sections and appendices?
• We must write/find the missing content (maybe its buried somewhere in one of these other files)
• The Troubleshooting section and Appendices B and C are way out of hand in terms of the TOC listings. Modify the stuff so that it has a more reasonable number of level two items

Overview

Hyrax.adoc

This is the source of the overview text. It has some notes about changes to the presentation of the overview. I think the OPeNDAP Hyrax development is sponsored by section should be in the acknowledgements subsection of the (now empty) Preface.

Installation

Master_Hyrax_OLFS_Installation.adoc

No notes except that this contains a link to the vanished BES_Installation file.

Configuration

Master_Hyrax_Configuration.adoc

A set of includes; see below.

Hyrax_Configuration.adoc

Included by Master_Hyrax_Configuration.adoc

Hyrax_BES_Configuration.adoc

Included by Master_Hyrax_Configuration.adoc. Also art of Troubleshooting

Hyrax_OLFS_Configuration.adoc

Included by Master_Hyrax_Configuration.adoc

Hyrax_Configuring_The_OLFS_To_Work_With_Multiple_BES's.adoc

Included by Master_Hyrax_Configuration.adoc

Hyrax_Logging_Configuration.adoc

Included by Master_Hyrax_Configuration.adoc

Hyrax_THREDDS_Configuration.adoc

Included by Master_Hyrax_Configuration.adoc

Master_Hyrax_Customizing_Hyrax.adoc

Part of the Configuration section

Master_Hyrax_Apache_Integration.adoc

Part of Configuration

Operation

Hyrax_Starting_and_stopping_the_BES.adoc

No includes or notes. Part of Operation

Master_Hyrax_Administrators_Interface.adoc

Part of Operation

Security

Master_Hyrax_Secure_Installation_Guidelines.adoc

Part of Security

Master_Hyrax_User_Authentication.adoc

Part of Security

Troubleshooting

Master_Troubleshooting.adoc

includes files...

Hyrax_BES_Client_commands.adoc

Part of Troubleshooting Think about moving this to Appendix E and adding text in Running bescmdln that says, "For a full listing of the commands, see..."

Hyrax_Running_bescmdln.adoc

Part of Troubleshooting

BES_How_to_Debug_the_BES.adoc

Part of Troubleshooting

Appendices

Master_Hyrax_WMS.adoc

Appendix A, does not include files.

Master_Handlers.adoc

Appendix B; includes all of the handler documentation files

Master_Aggregation.adoc

Appendix C; includes all of the files about aggreation.

Master_Hyrax_Sample_BES_Installations.adoc

Master_Server_Side_Processing_Functions.adoc

Appendix D; no includes

BES_XML_Commands.adoc

Appendix E.

This needs significant work in both presentation and content. We need to decide how to fix the TOC it uses. We also need to add information on the DAP commands, since they are missing.

Also, we might move the BES Client Commands and text from Troubleshooting to here and then refer to the appendix in the text there.

Unused files

In the aggreagtion directory:

• Use_cases_for_swath_and_time_series_aggregation.adoc - Somwhow this is actually an HTML file.
• THREDDS_using_XSLT.adoc

About these files

These files are derived from the Hyrax documentation pages on docs.OPeNDAP.org. I've extracted them from the files in documentation/other and then grouped them into the files in this directory and those in the sub-directories handlers and aggregation. The latter two hold information abut specific handlers and the aggregation handler that are bundled with the server.

The files reference images in the documentation/images directory, and those links will need to be fixed, one way or another.

I will remove the files from documentation/other that are here, so there are no duplicates.

The files that start with the prefix Master: Some are composite documents, others are just one file.

The files that are prefixed with Hyrax: The original files from the wiki. Some of these are 'included' by the 'Master' documents.