Merge pull request #1068 from OSC/develop

Add all the 4.0 updates and release notes for publishing version 4.0.0 today.

.github/workflows/publish.yml

@@ -18,10 +18,19 @@ jobs:
       - name: checkout
         uses: actions/checkout@v3
 
+      - name: Setup ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Check Spelling
+        run: |
+          rake spellcheck || true
+
       - name: Make Html
         run: |
-          export OOD_BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}
-          docker run --rm -v "${PWD}:/doc" -u "$(id -u):$(id -g)" -e OOD_BRANCH ohiosupercomputer/ood-doc-build:v2.0.0 make html
+          rake build
 
       - name: Publish to the test repo
         run: GITHUB_TOKEN=${{ secrets.OSC_WIAG_PUB_REPO_TOKEN }} /bin/bash push.sh "ood-documentation-test"

Makefile

@@ -223,3 +223,9 @@ dummy:
 	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
 	@echo
 	@echo "Build finished. Dummy builder generates no files."
+
+.PHONY: spellcheck
+spellcheck:
+	$(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) $(BUILDDIR)
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

Rakefile

@@ -5,13 +5,12 @@ end
 
 desc "Build docs using docker"
 task :build do
-  if podman?
-    exec "podman run --rm -it -v #{__dir__}:/doc #{image} make html"
-  elsif docker?
-    exec "docker run --rm -it -v '#{__dir__}:/doc' -u '#{user_group}' #{image} make html"
-  else
-    raise StandardError, "Cannot find any suitable container runtime to build. Need 'podman' or 'docker' installed."
-  end
+  exec "#{run_cmd} make html"
+end
+
+desc "Spellcheck"
+task :spellcheck do
+  exec "#{run_cmd} make spellcheck"
 end
 
 desc "Open built documentation in browser"
@@ -25,7 +24,7 @@ def user_group
 end
 
 def image
-  'ohiosupercomputer/ood-doc-build:v2.0.0'
+  'ohiosupercomputer/ood-doc-build:v3.1.0'
 end
 
 def docker?
@@ -37,3 +36,13 @@ def podman?
   `which podman 2>/dev/null 2>&1`
   $?.success?
 end
+
+def run_cmd
+  if podman?
+    "podman run --rm -it -v #{__dir__}:/doc #{image}"
+  elsif docker?
+    "docker run --rm -it -v '#{__dir__}:/doc' -u '#{user_group}' #{image}"
+  else
+    raise StandardError, "Cannot find any suitable container runtime to build. Need 'podman' or 'docker' installed."
+  end
+end

source/architecture.rst

@@ -5,9 +5,9 @@ Architecture
 
 Below are some diagrams of OnDemand's architecture:
 
-#. Overview is a high level visual generated from Powerpoint.
+#. Overview is a high level visual generated from PowerPoint.
 #. System context and Container context diagrams below follow the `C4 <https://c4model.com/>`_.
-   model for software diagrams, are more technically detailed and are built using draw.io
+   model for software diagrams, are more technically detailed and are built using ``draw.io``
 #. Request flow diagram is a sequence diagram built using plantuml.
 
 Overview
@@ -97,7 +97,7 @@ Linux Host Adapter
 .. figure:: /app-flow-diagrams/flow_linux_host_adapter.png
 
 ===========
-Rstudio Job
+RStudio Job
 ===========
 
 .. figure:: /app-flow-diagrams/flow_rstudio_job.png

source/authentication.rst

@@ -21,7 +21,7 @@ No Open OnDemand functionality is available without authentication.
    If you managed to install an Apache authentication module at your center
    that currently does not have a tutorial listed below we would greatly
    appreciate it if you could take the time to contribute a detailed
-   walkthrough.
+   walk-through.
 
 
 .. tip::

source/authentication/adfs-with-auth-mellon.rst

@@ -81,7 +81,7 @@ Note that this configuration assumes that SAML has been configured such that the
         MellonEnable "auth"
       </Location>
 
-#. Convert the key and cert files into pfx format
+#. Convert the key and cert files into PFX format
 
    .. code-block:: shell
 

source/authentication/dex.rst

@@ -8,7 +8,7 @@ OpenID Connect with Dex
 Installing OnDemand Dex package
 -------------------------------
 
-First the OnDemand yum repos must be enabled, see :ref:`install-software`.
+First the OnDemand yum repositories must be enabled, see :ref:`install-software`.
 
 Install the ``ondemand-dex`` package:
 
@@ -36,7 +36,7 @@ Requirements:
 - Git
 - Make
 
-Build and install the ondemand-dex binary:
+Build and install the ``ondemand-dex`` binary:
 
    .. code-block:: sh
 
@@ -53,7 +53,7 @@ Add the ``ondemand-dex`` user and group:
       sudo groupadd -r ondemand-dex
       sudo useradd -r -d /var/lib/ondemand-dex -g ondemand-dex -s /sbin/nologin -c "OnDemand Dex" ondemand-dex
 
-Get ``ondemand-dex`` repo and install web files and systemd unit file
+Get the ``ondemand-dex`` repository and install web files and systemd unit file
 
    .. code-block:: sh
 
@@ -96,7 +96,7 @@ The service for OnDemand Dex is ``ondemand-dex``:
 OnDemand Dex behind Apache reverse proxy
 ----------------------------------------
 
-By default Dex sits behing Apache and is accessed via a reverse proxy.
+By default Dex sits behind Apache and is accessed via a reverse proxy.
 OnDemand Dex behind the reverse proxy logic will force Dex to listen only on ``localhost`` and only
 via HTTP.
 
@@ -120,13 +120,13 @@ Dex Firewall
 
 By default when using SSL, Dex will use port ``5554`` for the communication between OnDemand and Dex as well as login interactions with users accessing OnDemand.  The port used for non-SSL is ``5556``.  The port being used by Dex must be externally accessible.
 
-Firewalld example:
+firewalld example:
    .. code-block:: sh
 
       $ sudo firewall-cmd --zone=public --add-port=5554/tcp --permanent
       $ sudo firewall-cmd --reload
 
-Iptables example:
+iptables example:
    .. code-block:: sh
 
       $ sudo iptables -I INPUT -p tcp -m tcp --dport 5554 -j ACCEPT

source/authentication/duo-2fa-with-keycloak.rst

@@ -8,7 +8,7 @@ These are the steps to setup two factor authentication with Duo using Keycloak.
 Install Keycloak Duo SPI
 --------------------------------------------------
 
-#. Clone the Keycloak Duo SPI repo
+#. Clone the Keycloak Duo SPI repository.
 
    .. code::
 
@@ -50,11 +50,11 @@ Configure Duo SPI
 --------------------------------------------------
 
 #. Log into your Keycloak instance
-#. Choose the realm to configure in upper left corner, eg ``ondemand``
+#. Choose the realm to configure in upper left corner, e.g., ``ondemand``
 #. Choose ``Realm Settings`` in the left menu then ``Security Defenses`` tab
 #. Add ``frame-src https://*.duosecurity.com/ 'self';`` to the beginning of the value for ``Content-Security-Policy``
 #. Choose ``Authentication`` in the left menu
-#. While on ``Flows`` tab ensure the dropdown for the flow name is ``Browser`` and click ``Copy``
+#. While on ``Flows`` tab ensure the drop-down for the flow name is ``Browser`` and click ``Copy``
 #. Name the new flow ``browser-with-duo``
 #. For all items below ``Username Password Form`` delete them by choosing ``Actions`` then ``Delete``
 #. Choose ``Actions`` for ``Browser-with-duo Forms`` and choose ``Add Execution``

source/authentication/nsf-access.rst

@@ -4,7 +4,7 @@ NSF ACCESS
 ----------
 
 If your site is a part of the `National Science Foundation`_'s (NSF)
-`ACCESS`_ program (formerley `XSEDE`_) you can use their Identity Provider (IDP)
+`ACCESS`_ program (formerly `XSEDE`_) you can use their Identity Provider (IDP)
 to authenticate users for your Open OnDemand instance.
 
 OIDC Client Registration
@@ -15,7 +15,7 @@ instance as an Open ID Connect (OIDC) client.
 ACCESS uses `CILogon`_ to provide a bridge from campus authentication, via the InCommon Federation,
 to OAuth/OIDC-based research cyberinfrastructure (CI).
 
-Once you've registered your Open OnDemand instance, you can then configure it accordingly.
+Once you have registered your Open OnDemand instance, you can then configure it accordingly.
 Since `ACCESS`_ uses Open ID Connect (OIDC) you can see our :ref:`oidc documentation <authentication-oidc>`
 for more details on how to configure Open OnDemand with what CILogon has provided in
 registering your application.
@@ -49,7 +49,7 @@ Shibboleth and InCommon
 If your campus already runs Shibboleth authentication, you have an alternative to the Open ID Connect
 configuration above.
 
-The SAML metadata for idp.access-ci.org is published by InCommon and can be downloaded using the 
+The SAML metadata for ``idp.access-ci.org`` is published by InCommon and can be downloaded using the 
 Metadata Query (MDQ) Service from https://mdq.incommon.org/entities/https%3A%2F%2Faccess-ci.org%2Fidp . 
 Alternatively, you can download the metadata from https://identity.access-ci.org/access-metadata.xml 
 and configure it in a local file.

source/authentication/oidc.rst

@@ -12,7 +12,7 @@ The following prerequisites need to be satisfied:
 
 .. note::
 
-   The OnDemand repos have the ``mod_auth_openidc`` RPM for RHEL 8 and Rocky 8 that are newer than what the OS provides to make use of some newer features.
+   The OnDemand repositories have the ``mod_auth_openidc`` RPM for RHEL 8 and Rocky 8 that are newer than what the OS provides to make use of some newer features.
 
 The following is an example :program:`ood-portal-generator` configuration file:
 

source/authentication/overview/configure-logout.rst

@@ -3,9 +3,9 @@
 Configure Logout
 ================
 
-The logout link on the dashboard is ``/logout``. OnDemand's Apache config has a separate directive to handle ``/logout``, which by default redirects the user to ``/pun/sys/dashboard/logout``, which is a default logout page displayed by the dashboard. Because authentication handled by Apache, this approach enables the logout URL to be changed based on the authentication strategy used.
+The logout link on the dashboard is ``/logout``. OnDemand's Apache configuration has a separate directive to handle ``/logout``, which by default redirects the user to ``/pun/sys/dashboard/logout``, which is a default logout page displayed by the dashboard. Because authentication handled by Apache, this approach enables the logout URL to be changed based on the authentication strategy used.
 
-To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOUT/USER"`` in the ood-portal-generator config at ``/etc/ood/config/ood_portal.yml`` and regenerate the config.
+To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOUT/USER"`` in the ``ood-portal-generator`` configuration at ``/etc/ood/config/ood_portal.yml`` and regenerate the configuration.
 
 
 .. describe:: logout_redirect (String, null)
@@ -20,14 +20,14 @@ To change the logout_redirect URL, set ``logout_redirect: "https:://URL/TO/LOGOU
           logout_redirect: "/pun/sys/dashboard/logout"
 
      Using OpenID Connect Apache module
-       Redirect to the mod_auth_oidc logout location:
+       Redirect to the ``mod_auth_oidc`` logout location:
 
        .. code-block:: yaml
 
           logout_redirect: "/oidc?logout=https%3A%2F%2Fondemand.my-center.edu"
 
      Using Shibboleth Apache module
-       If the Shibboleth IdP server deployed is at idp.my-center.edu, this is an example redirect with mod_auth_shib:
+       If the Shibboleth IdP server deployed is at ``idp.my-center.edu``, this is an example redirect with ``mod_auth_shib``:
 
        .. code-block:: yaml
 

source/authentication/overview/map-user.rst

@@ -19,11 +19,16 @@ Since 2.0 you should use the simpler and faster :ref:`user_map_match <ood-portal
 
 Both with variations will be discussed here.
 
+.. tip::
+
+  Since 4.0 user mapping also accepts UIDs to be returned as well as usernames.
+  This can be helpful at centers where duplicate usernames and/or have multiple
+  domains.
 
 Remote User
 -----------
 
-It's worth discussusing where ``REMOTE_USER`` is coming from.  When apache
+It's worth discussing where ``REMOTE_USER`` is coming from.  When apache
 has successfully authenticates a request it sets the variable ``REMOTE_USER``
 from, well, the remote.
 
@@ -39,11 +44,11 @@ If you're using an OpenID Connect provider you may need to set
 tells apache how to set ``REMOTE_USER`` from the claim response.
 
 
-Reguluar Expression User Mapping
---------------------------------
+Regular Expression User Mapping
+-------------------------------
 
 The simplest and fastest way to map a ``REMOTE_USER`` to a system user is through
-:ref:`user_map_match <ood-portal-generator-user-map-match>`.  It isn't directly
+:ref:`user_map_match <ood-portal-generator-user-map-match>`.  This is not directly
 regular expression matching, but it's close enough for most use cases.
 See it's documentation for examples and more.
 
@@ -52,7 +57,7 @@ Dex Automatic Configuration
 
 When using the OpenId Connector `dex`_ and setting `oidc_remote_user_claim`_
 to ``email`` we automatically set `user_map_match`_ to ``^([^@]+)@.*$`` as
-a convienience.
+a convenience.
 
 User Map Command for Advanced Mappings
 --------------------------------------
@@ -69,12 +74,12 @@ configuration and be sure to make this mapping script executable.
   Be aware, this script is executed on every request.
 
 Let's take a simple example.  It uses bash's builtin regular expression matching
-against ``([^@]+)@osc.edu`` - an osc dot edu email address.  If that matches against 
-``$1`` (the ``REMOTE_USER``) after it's url-decoded, then we return an all lowercase
+against ``([^@]+)@osc.edu`` - an ``osc.edu`` email address.  If that matches against 
+``$1`` (the ``REMOTE_USER``) after it's URL decoded, then we return an all lowercase
 version of the first part of an email address.
 
-The contract this script has with ood is that ``REMOTE_USER`` is url-encoded and
-passed into it as the first arguement, ``$1``.
+The contract this script has with Open OnDemand is that ``REMOTE_USER`` is URL encoded and
+passed into it as the first argument, ``$1``.
 
 The script will return 0 and output the match if it can correctly map the user.
 Otherwise, if it fails, it will output nothing and exit 1.

source/authentication/shibboleth.rst

@@ -8,12 +8,12 @@ The following prerequisites need to be satisfied:
 - A Shibboleth IdP server deployed, e.g., ``idp.my-center.edu`` (outside of
   scope of this document)
 - The `Apache module for Shibboleth`_ installed on the OnDemand Server and
-  properly configured with its own Apache config (outside of scope of this
+  properly configured with its own Apache configuration (outside of scope of this
   document)
 
 .. warning::
 
-   It is required you turn on ``ShibCompatValidUser`` in your Apache config
+   It is required you turn on ``ShibCompatValidUser`` in your Apache configuration
    when setting up the Shibboleth module for Apache above.
 
    .. code-block:: apache

source/authentication/tutorial-oidc-keycloak-rhel7/add-custom-theme.rst

@@ -28,9 +28,3 @@ Here are two links to get started with a custom theme:
 Remember after adding a theme you still need to configure your realm in the
 Keycloak admin UI to use the theme for the login pages.
 
-.. note::
-
-   Soon we will offer an ood-keycloak base theme that be easier to extended to
-   provide most of the common themeing a site might like to perform. It will
-   also work well for OTP views.
-

source/conf.py

@@ -38,7 +38,8 @@
     'sphinx.ext.githubpages',
     'sphinxcontrib.httpdomain',
     'sphinxcontrib.plantuml',
-    'sphinx_tabs.tabs'
+    'sphinx_tabs.tabs',
+    'sphinxcontrib.spelling'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -68,16 +69,16 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'3.1'
+version = u'4.0'
 # The full version, including alpha/beta/rc tags.
-release = u'3.1.0'
+release = u'4.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -405,9 +406,12 @@ def rstjinja(app, docname, source):
 
 def setup(app):
     app.connect('source-read', rstjinja)
-    app.add_stylesheet('css/custom.css')
+    app.add_css_file('css/custom.css')
 
 # Context used for jinja template
 doc_context = {
     'ondemand_version':              version,
 }
+
+# spelling configurations
+spelling_ignore_contributor_names = False