Merge pull request #934 from OSC/develop

merge develop into latest to release 3.1.
OSC · Feb 20, 2024 · d022340 · d022340
2 parents 2e169c3 + 70b2a3d
commit d022340
Show file tree

Hide file tree

Showing 27 changed files with 1,176 additions and 272 deletions.
diff --git a/source/authentication/dex.rst b/source/authentication/dex.rst
@@ -10,11 +10,22 @@ Installing OnDemand Dex package
 
 First the OnDemand yum repos must be enabled, see :ref:`install-software`.
 
-Install the ``ondemand-dex`` RPM:
+Install the ``ondemand-dex`` package:
 
-   .. code-block:: sh
+.. tabs::
+
+   .. tab:: yum/dnf
+
+      .. code-block:: sh
+
+         sudo yum install ondemand-dex
+
+
+   .. tab:: apt
+
+      .. code-block:: sh
 
-      sudo yum install ondemand-dex
+         sudo apt-get install ondemand-dex
 
 Installing OnDemand Dex from source
 -----------------------------------

diff --git a/source/conf.py b/source/conf.py
@@ -68,9 +68,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'3.0'
+version = u'3.1'
 # The full version, including alpha/beta/rc tags.
-release = u'3.0.3'
+release = u'3.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/source/customizations.rst b/source/customizations.rst
@@ -73,6 +73,12 @@ To display a MOTD file on the Dashboard ensure that the environment variables ``
 .. tip::
     The ``_erb`` formats support ERB rendering to generate more dynamic messages.
 
+.. warning::
+  Some MOTD formats like ``rss``, ``markdown`` and ``markdown_erb`` can contain malicous
+  HTML content. For your safety, by default, the Open OnDemand system will not render
+  HTML.  We provide :ref:`a configuration to enable HTML rendering in MOTD <motd_render_html>`
+  should you need to render HTML.
+
 .. figure:: /images/dashboard_motd.png
    :align: center
 

diff --git a/source/how-tos/analytics/google-analytics.rst b/source/how-tos/analytics/google-analytics.rst
@@ -20,76 +20,21 @@ If you wish you can setup your Open-OnDemand instance to send usage data to Goog
 
 Configure Open OnDemand
 --------------------------
-Add your google analytics id your ood_portal.yml file.
 
-.. code-block:: yaml
+Refer to the :ref:`ondemand.d configuration property google_analytics_tag_id <google_analytics_tag_id>`
+on how to configure this feature.
 
-  # /etc/ood/config/ood_portal.yml
-  ---
-
-  analytics:
-    # the id will be specific to your account, but url is likely the same
-    id: UA-99999999-1
-    url: "http://www.google-analytics.com/collect"
-
-This configuration will generate a block similar to this in your apache's 
-``ood-portal.conf`` file (after running the ood-portal-generator). 
-
-.. code-block:: apache
-
-  <Location "/pun">
-    ...
-
-    SetEnv OOD_ANALYTICS_TRACKING_URL "http://www.google-analytics.com/collect"
-    SetEnv OOD_ANALYTICS_TRACKING_ID  "UA-99999999-1"
-    LuaHookLog analytics.lua analytics_handler
-  </Location>
-
-Configure Google Analytics
-------------------------------
-
-You'll need to create all of these custom dimensions and custom metrics in the appropriate GA
-account(s). 
-
-.. warning::
-
-  Order matters here! Index numbers are given to ensure you create and define these
-  items in the correct order.  Otherwise Google Analytics will be incorrectly indexing
-  these metrics.
-
-  As an example say Username gets index 3 instead of index 1. Now when you query for 
-  `dimension3` thinking it's timestamps, you'll get back usernames instead!
-
-.. table:: GA custom dimensions
-   :widths: auto
-
-   =================== ======== ============
-    Name                 Index    Scope
-   =================== ======== ============
-   Username                1        User
-   Session ID              2        Session
-   Timestamp               3        Hit
-   Remote Username         4        Hit
-   Request Method          5        Hit
-   Request Status          6        Hit
-   Document Referrer       7        Hit
-   =================== ======== ============
-
-.. table:: GA custom metrics
-   :widths: auto
-
-   =================== ======== ============ ================
-    Name                 Index    Scope      Formatting Type
-   =================== ======== ============ ================
-   Proxy Time             1        Hit            Integer
-   User Map Time          2        Hit            Integer
-   =================== ======== ============ ================
 
 Querying Google Analytics
 ---------------------------
 
 .. _GA client libraries: https://developers.google.com/analytics/devguides/reporting/core/v3/libraries
 
+.. warning::
+  This documentation is for GA version 3. With the newer versions of GA this may not
+  work as intended. As OSC does not use GA we're unable to update these examples
+  ourselves, but would accept updates for the same.
+
 Now that you have Open-OnDemand sending information to GA and it's all configured correctly,
 you can now query GA for this information, parse it and present it in any fashion you like. 
 

diff --git a/source/how-tos/app-development/interactive.rst b/source/how-tos/app-development/interactive.rst
@@ -9,12 +9,14 @@ currently provided for all Open OnDemand applications but requires further
 
 An Interactive App is a plugin that follows a custom
 file/directory structure and API that can be described by the five stages:
-:ref:`app-development-manifest`
+:ref:`app-development-manifest`,
 :ref:`app-development-interactive-form`,
 :ref:`app-development-interactive-template`,
-:ref:`app-development-interactive-submit`, and
+:ref:`app-development-interactive-submit` and
 :ref:`app-development-interactive-view`.
 
+Additionally, there is :ref:`app-development-interactive-additional-info`.
+
 A typical file/directory structure for an Interactive App can look like::
 
   my_app/
@@ -24,7 +26,9 @@ A typical file/directory structure for an Interactive App can look like::
   ├── template
   │   ├── before.sh.erb
   │   └── script.sh.erb
-  └── view.html.erb
+  ├── view.html.erb
+  ├── info.{md,html}.erb
+  └── completed.{md,html}.erb
 
 Each of these files/directories are described below in their respective stage.
 
@@ -41,3 +45,4 @@ Each of these files/directories are described below in their respective stage.
    interactive/view
    interactive/sub-apps
    interactive/conn-params
+   interactive/additional-info
diff --git a/source/how-tos/app-development/interactive/additional-info.rst b/source/how-tos/app-development/interactive/additional-info.rst
@@ -0,0 +1,47 @@
+.. _app-development-interactive-additional-info:
+
+Adding Additional Information to the session cards
+==================================================
+
+.. _bc_info_html_md_erb:
+
+info.{md,html}.erb
+------------------
+
+It's possible for you to add additional information to this session's card.
+
+You can do so by creating a Markdown file ``info.md.erb`` or an html file
+``info.html.erb`` in the applications folder.  Markdown files get generated
+into html with # turning into an <h1> and ## turning into an <h2> and so on.
+
+Again, they're `eRuby (Embedded Ruby)`_ files so you can add some dynamic behavior
+to them. Along with any library you may choose to use you can also access these
+variables directly.
+
+id
+  The session UUID of the job
+cluster_id
+  The cluster the job was submitted to
+job_id
+  The job id from the scheduler
+created_at
+  The time the session was created
+
+
+.. _bc_completed_html_md_erb:
+
+completed.{md,html}.erb
+------------------------
+
+:ref:`bc_info_html_md_erb` above will display on the session's card
+regardless of the state of the job - it will always be displayed.
+
+``completed.{md,html}.erb`` on the other hand, will only display
+once the job has reached the ``completed`` state.
+
+You may want to add this to the session's card to display information
+to the user when the job is completed. Again, as it's `eRuby (Embedded Ruby)`_
+files so you can add some dynamic behavior to them. 
+
+
+.. _eruby (embedded ruby): https://en.wikipedia.org/wiki/ERuby
diff --git a/source/how-tos/app-development/interactive/dynamic-form-widgets.rst b/source/how-tos/app-development/interactive/dynamic-form-widgets.rst
@@ -95,6 +95,24 @@ instructs the webpage to hide the ``cuda_version`` when the ``standard``
         - 'gpu'
 
 
+Additionally, you can use ``check_box`` widgets to hide elements.
+Here we have a checkbox ``enable_cuda_version`` that will show
+``cuda_version`` when checked and hide it when it's not checked.
+
+.. tip::
+  Checkboxes respond to ``when-checked: true`` and ``when-unchecked: true``
+  for hiding elements when checked or unchecked.
+
+.. code-block:: yaml
+  :emphasize-lines: 6
+
+  attributes:
+    enable_cuda_version:
+      widget: 'check_box'
+      html_options:
+        data:
+          hide-cuda-version-when-unchecked: true
+
 Dynamic Min and Maxes
 *********************
 
@@ -149,22 +167,31 @@ account automatically based on the selection of node type.
 In this example, when ``standard`` ``node_type`` is chosen, the ``charge_account`` element
 will be automatically set to ``standard-charge-code``.
 
+In addition to setting strings, option choices can also set check boxes.
+You will see in this example that when you change the ``node_type`` selection
+the ``enable_gpu`` check box will either be checked or unchecked.
+
 .. code-block:: yaml
 
   form:
+    - enable_gpu
     - charge_account
     - node_type
   attributes:
+    enable_gpu:
+      widget: check_box
     node_type:
       widget: select
       options:
         - [ 
             'standard', 'standard',
-            data-set-charge-account: 'standard-charge-code'
+            data-set-charge-account: 'standard-charge-code',
+            data-set-enable-gpu: 0
           ]
         - [
             'gpu', 'gpu',
             data-set-charge-account: 'gpu-charge-code',
+            data-set-enable-gpu: 1
           ]