diff --git a/source/authentication/dex.rst b/source/authentication/dex.rst index 48d3ec1f0..371208195 100644 --- 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 index b29179111..e34feff2c 100644 --- 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 index 803f1aeb4..0c6dfb967 100644 --- 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 ` + 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 index 8254a322f..f33c25880 100644 --- 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 ` +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 - - - ... - - SetEnv OOD_ANALYTICS_TRACKING_URL "http://www.google-analytics.com/collect" - SetEnv OOD_ANALYTICS_TRACKING_ID "UA-99999999-1" - LuaHookLog analytics.lua analytics_handler - - -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 index 8f1608206..10f09e0e0 100644 --- 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 new file mode 100644 index 000000000..94a4d60fb --- /dev/null +++ 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

and ## turning into an

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 index 9e46df628..9d094e486 100644 --- 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 ] diff --git a/source/how-tos/app-development/interactive/form-widgets.rst b/source/how-tos/app-development/interactive/form-widgets.rst index c69da5d9d..b2df20bd5 100755 --- a/source/how-tos/app-development/interactive/form-widgets.rst +++ b/source/how-tos/app-development/interactive/form-widgets.rst @@ -1,128 +1,157 @@ -.. _form-widgets: - -Form Widgets -============ - Checkbox (check_box) - A checkbox. Note that you can change the checked and unchecked values. For example changing - them from ``1`` and ``0`` to ``yes`` and ``no``. - - .. code-block:: yaml - - test_checkbox: - widget: check_box - checked_value: 1 - unchecked_value: 0 - label: "Test Checkbox" - help: | - Your help message - -================================================================== - - Hidden Field (hidden_field) - A hidden field that will not be shown, but will still be in the HTML. - - .. code-block:: yaml - - test_hidden_field: - widget: "hidden_field" - value: "Test Hidden Field Value" - -================================================================== - - Number Field (number_field) - A number field. - - .. code-block:: yaml - - num_cores: - widget: "number_field" - label: "Number of cores" - value: 1 - help: | - Your help message - min: 1 - max: 28 - step: 1 - -================================================================== - - Radio Button (radio_button) - Note that in the options below, the text to display is on the left of the comma, and the select value is on the right of the comma. - The value: key represents the default selection. - - .. code-block:: yaml - - mode: - widget: "radio_button" - value: "1" - help: | - Your help message - options: - - ["Jupyter Lab", "1"] - - ["Jupyter Notebook", "0"] - -================================================================== - - Resolution Field (resolution_field) - Change the resolution for interactive applications that use VNC. - - .. code-block:: yaml - - test_resolution_field: - widget: "resolution_field" - label: "Test Resolution Field" - required: true - help: | - Your help message - -================================================================== - - Select Field (select) - Note that in the options below, the text to display is on the left of the comma, and the select value is on the right of the comma. - - .. code-block:: yaml - - version: - widget: "select" - label: "JupyterLab Version" - options: - - [ "3.0", "app_jupyter/3.0.17" ] - - [ "2.3", "app_jupyter/2.3.2" ] - - [ "2.2", "app_jupyter/2.2.10" ] - - [ "1.2", "app_jupyter/1.2.21" ] - help: | - Your help message - -================================================================== - - TextArea Field (text_area) - A text area. This allows for multiple lines of text input. - - .. code-block:: yaml - - test_text_area: - widget: "text_area" - label: "Test Text Area" - value: "Test Text Area Value" - help: | - Your help message - -================================================================== - - Text Field (text_field) - A text field. This only allows for a single line of text input. - - .. code-block:: yaml - - test_text_field: - widget: "text_field" - label: "Test Text Field" - value: "Test Text Value" - help: | - Your help message - -================================================================== - - - -.. _markdown: https://en.wikipedia.org/wiki/Markdown +.. _form-widgets: + +Form Widgets +============ + Checkbox (check_box) + A checkbox. Note that you can change the checked and unchecked values. For example changing + them from ``1`` and ``0`` to ``yes`` and ``no``. + + .. code-block:: yaml + + test_checkbox: + widget: check_box + checked_value: 1 + unchecked_value: 0 + label: "Test Checkbox" + help: | + Your help message + +================================================================== + + Hidden Field (hidden_field) + A hidden field that will not be shown, but will still be in the HTML. + + .. code-block:: yaml + + test_hidden_field: + widget: "hidden_field" + value: "Test Hidden Field Value" + +================================================================== + + Number Field (number_field) + A number field. + + .. code-block:: yaml + + num_cores: + widget: "number_field" + label: "Number of cores" + value: 1 + help: | + Your help message + min: 1 + max: 28 + step: 1 + +================================================================== + + Radio Button (radio_button) + Note that in the options below, the text to display is on the left of the comma, and the select value is on the right of the comma. + The value: key represents the default selection. + + .. code-block:: yaml + + mode: + widget: "radio_button" + value: "1" + help: | + Your help message + options: + - ["Jupyter Lab", "1"] + - ["Jupyter Notebook", "0"] + +================================================================== + + Resolution Field (resolution_field) + Change the resolution for interactive applications that use VNC. + + .. code-block:: yaml + + test_resolution_field: + widget: "resolution_field" + label: "Test Resolution Field" + required: true + help: | + Your help message + +================================================================== + + Select Field (select) + Note that in the options below, the text to display is on the left of the comma, and the select value is on the right of the comma. + + .. code-block:: yaml + + version: + widget: "select" + label: "JupyterLab Version" + options: + - [ "3.0", "app_jupyter/3.0.17" ] + - [ "2.3", "app_jupyter/2.3.2" ] + - [ "2.2", "app_jupyter/2.2.10" ] + - [ "1.2", "app_jupyter/1.2.21" ] + help: | + Your help message + +================================================================== + + TextArea Field (text_area) + A text area. This allows for multiple lines of text input. + + .. code-block:: yaml + + test_text_area: + widget: "text_area" + label: "Test Text Area" + value: "Test Text Area Value" + help: | + Your help message + +================================================================== + + Text Field (text_field) + A text field. This only allows for a single line of text input. + + .. code-block:: yaml + + test_text_field: + widget: "text_field" + label: "Test Text Field" + value: "Test Text Value" + help: | + Your help message + +.. _path_selector: + +================================================================== + + Path Selector (path_selector) + A Path Selector. This is a special OnDemand feature that is not + directly an HTML input type. It builds a ``text_field`` input + type, but also provides a button that will provide a modal that + allows users to navigate through directories to select a path. + + This is useful in forms where a path must be selected and you + want to allow your users to choose an arbirary path. + + ``directory`` is the initial directory the path selector will open + to when the users opens the modal. This defaults to the users' HOME. + + ``show_hidden`` is a boolean flag to show hidden files or not. This + defaults to false - it will not show hidden files. + + ``show_files`` is a boolean flag to show files or not. This defaults + to true - it will show files. + + .. code-block:: yaml + + path: + widget: "path_selector" + directory: "/fs/ess/project" + show_hidden: true + show_files: false + +================================================================== + + +.. _markdown: https://en.wikipedia.org/wiki/Markdown diff --git a/source/how-tos/app-development/interactive/view.rst b/source/how-tos/app-development/interactive/view.rst index 2f5bbc568..5f91bada7 100644 --- a/source/how-tos/app-development/interactive/view.rst +++ b/source/how-tos/app-development/interactive/view.rst @@ -189,30 +189,6 @@ In this example, the password is stored in a hidden input field that the user doesn't see and it gets communicated to the Jupyter server in the ``POST`` request. -.. _bc_info_html_md_erb: - -Adding Additional Information to the panel ------------------------------------------- - -It's possible for you to add additional information to this connection view. - -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

and ## turning into an

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_native_vnc_view: Adding Native VNC instructions to the panel diff --git a/source/how-tos/debug/debug-apache.rst b/source/how-tos/debug/debug-apache.rst index a364d1c9c..2aa0eed6b 100644 --- a/source/how-tos/debug/debug-apache.rst +++ b/source/how-tos/debug/debug-apache.rst @@ -36,7 +36,7 @@ Restart services sudo systemctl try-restart httpd - .. tab:: Ubuntu + .. tab:: Ubuntu & Debian .. code-block:: sh @@ -73,7 +73,7 @@ Or you're using the wrong hostname in your browser. sudo /sbin/httpd -S - .. tab:: Ubuntu + .. tab:: Ubuntu & Debian .. code-block:: sh diff --git a/source/how-tos/monitoring/prometheus.rst b/source/how-tos/monitoring/prometheus.rst index 035461b86..05d53b049 100644 --- a/source/how-tos/monitoring/prometheus.rst +++ b/source/how-tos/monitoring/prometheus.rst @@ -25,7 +25,7 @@ Dependencies: Install via RPM -------------------------- -For RHEL/CentOS 7 and RHEL/Rocky 8 systems the `ondemand_exporter`_ can be installed via RPM. +For yum/dnf based systems the `ondemand_exporter`_ can be installed via RPM. .. code-block:: sh @@ -34,22 +34,24 @@ For RHEL/CentOS 7 and RHEL/Rocky 8 systems the `ondemand_exporter`_ can be insta The RPM will install the following files that should work out of the box: - **RHEL/CentOS 7 only**: /opt/rh/httpd24/root/etc/httpd/conf.d/ondemand_exporter.conf -- **RHEL/Rocky 8 only**: /etc/httpd/conf.d/ondemand_exporter.conf +- **RHEL/Rocky/AlmaLinux 8 & 9 only**: /etc/httpd/conf.d/ondemand_exporter.conf - /etc/sudoers.d/ondemand_exporter Ensure that the new Apache configuration is loaded by restarting Apache -RHEL/CentOS 7 +.. tabs:: - .. code-block:: sh + .. tab:: RHEL/CentOS 7 - sudo systemctl restart httpd24-httpd + .. code-block:: sh -RHEL/Rocky 8 + sudo systemctl restart httpd24-httpd - .. code-block:: sh + .. tab:: RHEL/Rocky/Alma Linux 8 & 9 - sudo systemctl restart httpd + .. code-block:: sh + + sudo systemctl restart httpd Start the service @@ -69,7 +71,7 @@ Check for the `ondemand_exporter Latest Release`_ version number. Replace ``VER .. code-block:: sh - VERSION="0.8.0" + VERSION="0.10.0" ARCHIVE="ondemand_exporter-${VERSION}.linux-amd64" wget -O /tmp/${ARCHIVE}.tar.gz https://github.com/OSC/ondemand_exporter/releases/download/v${VERSION}/${ARCHIVE}.tar.gz tar xf /tmp/${ARCHIVE}.tar.gz -C /tmp @@ -78,19 +80,21 @@ Check for the `ondemand_exporter Latest Release`_ version number. Replace ``VER sudo install -o root -g root -m 0644 /tmp/${ARCHIVE}/files/ondemand_exporter.service /etc/systemd/system/ sudo systemctl daemon-reload -RHEL/CentOS 7 +.. tabs:: - .. code-block:: sh + .. tab:: RHEL/CentOS 7 - sudo install -o root -g root -m 0440 /tmp/${ARCHIVE}/files/apache.conf /opt/rh/httpd24/root/etc/httpd/conf.d/ondemand_exporter.conf - sudo systemctl restart httpd24-httpd + .. code-block:: sh -RHEL/Rocky 8 + sudo install -o root -g root -m 0440 /tmp/${ARCHIVE}/files/apache.conf /opt/rh/httpd24/root/etc/httpd/conf.d/ondemand_exporter.conf + sudo systemctl restart httpd24-httpd - .. code-block:: sh + .. tab:: RHEL/Rocky/Alma Linux 8 & 9 + + .. code-block:: sh - sudo install -o root -g root -m 0440 /tmp/${ARCHIVE}/files/apache.conf /etc/httpd/conf.d/ondemand_exporter.conf - sudo systemctl restart httpd + sudo install -o root -g root -m 0440 /tmp/${ARCHIVE}/files/apache.conf /etc/httpd/conf.d/ondemand_exporter.conf + sudo systemctl restart httpd **(Optional)** If Passenger was not installed via ``ondemand-passenger`` RPM. Adjust the path to ``passenger-status`` as needed @@ -101,6 +105,7 @@ RHEL/Rocky 8 [Service] Environment="PASSENGER_STATUS=/usr/sbin/passenger-status" EOF + sudo systemctl daemon-reload Start the service diff --git a/source/images/develop_dashboard_grey_background.png b/source/images/develop_dashboard_grey_background.png new file mode 100644 index 000000000..8b5d636fd Binary files /dev/null and b/source/images/develop_dashboard_grey_background.png differ diff --git a/source/images/develop_dashboard_pinned_apps.png b/source/images/develop_dashboard_pinned_apps.png new file mode 100644 index 000000000..47afcee54 Binary files /dev/null and b/source/images/develop_dashboard_pinned_apps.png differ diff --git a/source/index.rst b/source/index.rst index 3c0858082..cb76b64b7 100644 --- a/source/index.rst +++ b/source/index.rst @@ -73,6 +73,7 @@ These are institutions who were early adopters or provided HPC resources for dev install-ihpc-apps tutorials/tutorials-interactive-apps tutorials/tutorials-passenger-apps + tutorials/tutorials-dashboard-apps .. toctree:: :maxdepth: 2 diff --git a/source/installation.rst b/source/installation.rst index bdc5586a3..050853fcb 100644 --- a/source/installation.rst +++ b/source/installation.rst @@ -6,7 +6,7 @@ Installation The OnDemand host machine needs to be setup *similarly* to a login node. This means that it will need: -- RedHat/CentOS 7+ or Ubuntu 20.04-22.04 +- RedHat/CentOS 7+ or Ubuntu 20.04-22.04 or Debian 12 or Amazon Linux 2023 - the resource manager (e.g., Torque, Slurm, or LSF) client binaries and libraries used by the batch servers installed - configuration on both OnDemand node **and batch servers** to be able to diff --git a/source/installation/add-ssl.rst b/source/installation/add-ssl.rst index a33df8b41..356a8460b 100644 --- a/source/installation/add-ssl.rst +++ b/source/installation/add-ssl.rst @@ -76,7 +76,7 @@ authority. sudo yum update ca-certificates - .. tab:: Ubuntu + .. tab:: Ubuntu & Debian .. code:: sh @@ -96,7 +96,7 @@ authority you're using and run these commands to copy it to the appropriate plac sudo cp /etc/pki/ca-trust/source/anchors/ sudo update-ca-trust - .. tab:: Ubuntu + .. tab:: Ubuntu & Debian .. code:: sh diff --git a/source/installation/install-software.rst b/source/installation/install-software.rst index d384cd1df..df24ef781 100644 --- a/source/installation/install-software.rst +++ b/source/installation/install-software.rst @@ -6,7 +6,7 @@ Install Software Open OnDemand uses these packages, among many others. - `Apache HTTP Server 2.4`_ -- Ruby 2.7 with :command:`rake`, :command:`bundler`, and development +- Ruby 3.0 with :command:`rake`, :command:`bundler`, and development libraries - Node.js 14 @@ -19,8 +19,8 @@ Some operating systems use `Software Collections`_ to satisfy these. .. warning:: - Be sure to check :ref:`Supported Operating Systems ` before proceeding with install to verify - you are on a supported operating system. + Be sure to check :ref:`Supported Operating Systems and Architectures ` before proceeding with install to verify + you are on a supported operating system and architecture. .. warning:: @@ -40,20 +40,21 @@ Some operating systems use `Software Collections`_ to satisfy these. sudo yum install centos-release-scl epel-release - .. tab:: RockyLinux 8 + .. tab:: RockyLinux/Alma Linux 8 .. code-block:: sh sudo dnf config-manager --set-enabled powertools sudo dnf install epel-release - sudo dnf module enable ruby:3.0 nodejs:14 + sudo dnf module enable ruby:3.1 nodejs:18 - .. tab:: RockyLinux 9 + .. tab:: RockyLinux/Alma Linux 9 .. code-block:: sh sudo dnf config-manager --set-enabled crb sudo dnf install epel-release + sudo dnf module enable ruby:3.1 nodejs:18 .. tab:: RHEL 7 @@ -74,7 +75,7 @@ Some operating systems use `Software Collections`_ to satisfy these. .. code-block:: sh sudo dnf install epel-release - sudo dnf module enable ruby:3.0 nodejs:14 + sudo dnf module enable ruby:3.1 nodejs:18 sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms @@ -83,6 +84,7 @@ Some operating systems use `Software Collections`_ to satisfy these. .. code-block:: sh sudo dnf install epel-release + sudo dnf module enable ruby:3.1 nodejs:18 sudo subscription-manager repos --enable codeready-builder-for-rhel-9-x86_64-rpms 2. Add repository and install @@ -90,26 +92,71 @@ Some operating systems use `Software Collections`_ to satisfy these. .. tabs:: - .. tab:: yum/dnf + .. tab:: RedHat/CentOS 7 .. code-block:: sh - sudo yum install https://yum.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web-{{ ondemand_version }}-1.noarch.rpm + sudo yum install https://yum.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web-{{ ondemand_version }}-1.el7.noarch.rpm sudo yum install ondemand + .. tab:: RedHat/Rocky Linux/AlmaLinux 8 - .. tab:: apt + .. code-block:: sh + + sudo dnf install https://yum.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web-{{ ondemand_version }}-1.el8.noarch.rpm + + sudo dnf install ondemand + + .. tab:: RedHat/Rocky Linux/AlmaLinux 9 + + .. code-block:: sh + + sudo dnf install https://yum.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web-{{ ondemand_version }}-1.el9.noarch.rpm + + sudo dnf install ondemand + + .. tab:: Ubuntu 20.04 + + .. code-block:: sh + + sudo apt install apt-transport-https ca-certificates + wget -O /tmp/ondemand-release-web_{{ ondemand_version }}.0-focal_all.deb https://apt.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web_{{ ondemand_version }}.0-focal_all.deb + sudo apt install /tmp/ondemand-release-web_{{ ondemand_version }}.0-focal_all.deb + sudo apt update + + sudo apt install ondemand + + .. tab:: Ubuntu 22.04 + + .. code-block:: sh + + sudo apt install apt-transport-https ca-certificates + wget -O /tmp/ondemand-release-web_{{ ondemand_version }}.0-jammy_all.deb https://apt.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web_{{ ondemand_version }}.0-jammy_all.deb + sudo apt install /tmp/ondemand-release-web_{{ ondemand_version }}.0-jammy_all.deb + sudo apt update + + sudo apt install ondemand + + .. tab:: Debian 12 .. code-block:: sh sudo apt install apt-transport-https ca-certificates - wget -O /tmp/ondemand-release-web_{{ ondemand_version }}.0_all.deb https://apt.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web_{{ ondemand_version }}.0_all.deb - sudo apt install /tmp/ondemand-release-web_{{ ondemand_version }}.0_all.deb + wget -O /tmp/ondemand-release-web_{{ ondemand_version }}.0-bookworm_all.deb https://apt.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web_{{ ondemand_version }}.0-bookworm_all.deb + sudo apt install /tmp/ondemand-release-web_{{ ondemand_version }}.0-bookworm_all.deb sudo apt update sudo apt install ondemand + .. tab:: Amazon Linux 2023 + + .. code-block:: sh + + sudo dnf install https://yum.osc.edu/ondemand/{{ ondemand_version }}/ondemand-release-web-{{ ondemand_version }}-1.amzn2023.noarch.rpm + + sudo dnf install ondemand + 3. Start services ----------------- @@ -130,13 +177,20 @@ Some operating systems use `Software Collections`_ to satisfy these. sudo systemctl start httpd sudo systemctl enable httpd - .. tab:: Ubuntu + .. tab:: Ubuntu & Debian .. code-block:: sh sudo systemctl start apache2 sudo systemctl enable apache2 + .. tab:: Amazon Linux 2023 + + .. code-block:: sh + + sudo systemctl start httpd + sudo systemctl enable httpd + 4. Verify installation ---------------------- @@ -151,7 +205,7 @@ After adding authentication, but before actually testing that it works, you shou You may also want to :ref:`enable SELinux `. -If you're seeing the default Apache page (Ubuntu users will) you will have to :ref:`debug virtualhosts ` +If you're seeing the default Apache page (Ubuntu & Debian users will) you will have to :ref:`debug virtualhosts ` and likely :ref:`configure a servername `. Building From Source diff --git a/source/installation/modify-system-security.rst b/source/installation/modify-system-security.rst index 34efb5412..e2a157b83 100644 --- a/source/installation/modify-system-security.rst +++ b/source/installation/modify-system-security.rst @@ -36,6 +36,7 @@ The custom SELinux booleans provided by the OnDemand SELinux policy: * ``ondemand_use_kubernetes`` (**default=off**): Allow OnDemand to interact with Kubernetes. * ``ondemand_use_ldap`` (**default=off**): Allows OnDemand to interact with remote LDAP servers. This does not affect Apache LDAP authentication. This is only necessary if the PUN is interacting with LDAP ports. * ``ondemand_use_kerberos`` (**default=off**): Allow OnDemand to interact with Kerberos. +* ``ondemand_use_smtp`` (**default=off**): Allow OnDemand to interact with SMTP for sending emails. The following SELinux booleans are enabled by the ``ondemand-selinux`` package: diff --git a/source/reference/files/nginx-stage-yml.rst b/source/reference/files/nginx-stage-yml.rst index 985a9d131..9658b0cd1 100644 --- a/source/reference/files/nginx-stage-yml.rst +++ b/source/reference/files/nginx-stage-yml.rst @@ -324,6 +324,28 @@ Configuration Options passenger_pool_idle_time: 900 +.. describe:: passenger_log_file (String) + + The log file that passenger will write standard out and standard + error to. + + .. note:: + You may use the variable ``%{user}`` to write user specific files. + + Default + Write to a per user location in ``/var/log/ondemand-nginx/``. + + .. code-block:: yaml + + passenger_log_file: '/var/log/ondemand-nginx/%{user}/error.log' + + Example + Write to a per user location in ``/some/other/location/``. + + .. code-block:: yaml + + passenger_log_file: '/some/other/location/%{user}/error.log' + .. describe:: passenger_options (Hash) A Hash of additional Passenger options diff --git a/source/reference/files/ondemand-d-ymls.rst b/source/reference/files/ondemand-d-ymls.rst index 643bc1612..f3da82c52 100644 --- a/source/reference/files/ondemand-d-ymls.rst +++ b/source/reference/files/ondemand-d-ymls.rst @@ -245,6 +245,28 @@ Configuration Properties with profile support custom_css_files: ["/myfolder/navigation.css", "/myfolder/pinned_apps.css"] +.. _custom_javascript_files: +.. describe:: custom_javascript_files (Array, []) + + List of relative URLs to custom javascript files to include in all Dashboard pages. + These javascript files can be used to customize the behavior of the Dashboard. + + The relative path will be prefixed with the value of the ``public_url`` property. + + Default + Empty list, no custom javascript files will be included. + + .. code-block:: yaml + + custom_javascript_files: [] + + Example + Add two custom Javascript files: ``/myfolder/navigation.js`` and ``/myfolder/pinned_apps.js`` to the Dashboard. + + .. code-block:: yaml + + custom_javascript_files: ["/myfolder/navigation.js", "/myfolder/pinned_apps.js"] + .. describe:: dashboard_title (String, 'Open OnDemand') The text to use as the main navigation logo. If the ``dashboard_header_img_logo`` property is defined, @@ -615,25 +637,26 @@ Configuration Properties module_file_dir: "/etc/reporting/modules" +.. _user_settings_file: .. describe:: user_settings_file (String, '.ood') - The name of the file to store user settings. This file is used to store the selected profile. - The path to the file is managed by the configuration variable ``Configuration.dataroot``. - This is usually: ``~/ondemand/data/sys/dashboard`` + The full path of the file to store user settings. This file is used to store + any user defined settings. Default A file called '.ood'. .. code-block:: yaml - user_settings_file: ".ood" + user_settings_file: "~/.config/ondemand/settings.yml" Example - Use ``user_settings.txt`` as the file name for user settings. + Use ``user_settings.txt`` as the file name for user settings + and change the path slightly. .. code-block:: yaml - user_settings_file: "user_settings.txt" + user_settings_file: "~/.config/local/open-ondemand/user_settings.txt" .. describe:: facl_domain (String, null) @@ -715,6 +738,65 @@ Configuration Properties remote_files_enabled: true + +.. describe:: remote_files_validation (Boolean, false) + + Enable validating remote files on startup. + + Default + Remote file systems will not be validated on startup. + + .. code-block:: yaml + + remote_files_validation: false + + Example + Remote file systems will be validated on startup. + + .. code-block:: yaml + + remote_files_validation: true + +.. _upload_enabled: +.. describe:: upload_enabled (Boolean, true) + + Enable uploading files. + + Default + File uploads are enabled. + + .. code-block:: yaml + + upload_enabled: true + + Example + File uploads are disabled. Users will not be able to upload + files through Open OnDemand. + + .. code-block:: yaml + + upload_enabled: false + +.. _downlad_enabled: +.. describe:: download_enabled (Boolean, true) + + Enable downloading files. + + Default + File downloads are enabled. + + .. code-block:: yaml + + download_enabled: true + + Example + File downloads are disabled. Users will not be able to download + files through Open OnDemand. + + .. code-block:: yaml + + download_enabled: false + .. describe:: hide_app_version (Boolean, false) Hide the interactive application's version. @@ -732,3 +814,102 @@ Configuration Properties .. code-block:: yaml hide_app_version: true + +.. _globus_endpoints: +.. describe:: globus_endpoints (Array, null) + + Add a Globus button to the file browser that opens the current directory + in the Globus transfer web app. + + Note that ``endpoint_path`` is the path that Globus will initialize to + and is very likely to be ``/`` regardless of the actual storage path. + + Default + Null, do not enable the Globus button + + Example + Use a single endpoint for the whole filesystem. + + .. code-block:: yaml + + globus_endpoints: + - path: "/" + endpoint: "716de4ac-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + endpoint_path: "/" + + Example + Use multiple endpoints. + + .. code-block:: yaml + + globus_endpoints: + - path: "/home" + endpoint: "716de4ac-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + endpoint_path: "/home" + + - path: "/project" + endpoint: "9f1fe759-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + endpoint_path: "/project" + + Example + When pathnames differ between the filesystem and endpoint. + + .. code-block:: yaml + + globus_endpoints: + - path: "/project" + endpoint: "9f1fe759-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + endpoint_path: "/" + + Example + Reference the home directory of the current user. + + .. code-block:: yaml + + globus_endpoints: + - path: "<%= Etc.getpwnam(Etc.getlogin).dir %>" + endpoint: "9f1fe759-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + endpoint_path: "/" + +.. _google_analytics_tag_id: + +.. describe:: google_analytics_tag_id (String, nil) + + Configure Google Analytics by supplying a tag id. + + Default + Google Analytics is disabled. + + .. code-block:: yaml + + google_analytics_tag_id: nil + + Example + Google Analytics is enabled and will upload data to the + tag id ``abc123``. + + .. code-block:: yaml + + google_analytics_tag_id: 'abc123' + + +.. _motd_render_html: +.. describe:: motd_render_html (Boolean, false) + + Render HTML in the Message of the Day (MOTD). This + configuration was added because some MOTD formats like + RSS can generate HTML that is potentially unsafe. + + Default + The Message of the day will not render HTML. + + .. code-block:: yaml + + motd_render_html: false + + Example + The Message of the day will render HTML. + + .. code-block:: yaml + + motd_render_html: true diff --git a/source/reference/files/ood-portal-yml.rst b/source/reference/files/ood-portal-yml.rst index 9c183d0f1..0180a2a5d 100644 --- a/source/reference/files/ood-portal-yml.rst +++ b/source/reference/files/ood-portal-yml.rst @@ -126,6 +126,7 @@ Configure General Options ssl: null Example + Supply ssl information. .. code-block:: yaml @@ -135,6 +136,27 @@ Configure General Options - SSLCertificateChainFile /etc/letsencrypt/live/change-me/chain.pem +.. _disable_logs: +.. describe:: disable_logs (Boolean, false) + + Disable logs in favor of supplying log directives in some other + configuration file. + + Default + Logs are enabled and defined in this virtual host. + + .. code-block:: yaml + + disable_logs: false + + Example + Disable logs in favor of supplying log directives in some other + configuration file. + + .. code-block:: yaml + + disable_logs: true + .. describe:: logroot (String) the root directory where log files are stored (can be relative to @@ -475,6 +497,48 @@ Configure General Options - "AuthType openid-connect" - "Require valid-user" +.. _custom_vhost_directives: +.. describe:: custom_vhost_directives (Array, []) + + Supply custom directives at the virtual host level. + + Default + No custom virtual host directives. + + .. code-block:: yaml + + custom_vhost_directives: [] + + Example + Add a single custom virutal host directive + to set an environment variable. + + .. code-block:: yaml + + custom_vhost_directives: + - SetEnv FOO BAR + +.. _custom_location_directives: +.. describe:: custom_location_directives (Array, []) + + Supply custom directives for every ``Location`` in the virtual host. + + Default + No custom location directives. + + .. code-block:: yaml + + custom_location_directives: [] + + Example + Add a single custom location directive + to set an environment variable. + + .. code-block:: yaml + + custom_location_directives: + - SetEnv FOO BAR + .. describe:: root_uri (String) the URI a user is redirected to when they access the root of the website diff --git a/source/release-notes.rst b/source/release-notes.rst index 69d1c6f16..a645b7e8a 100644 --- a/source/release-notes.rst +++ b/source/release-notes.rst @@ -6,6 +6,7 @@ Release Notes .. toctree:: :maxdepth: 2 + release-notes/v3.1-release-notes release-notes/v3.0-release-notes release-notes/v2.0-release-notes release-notes/v1.8-release-notes diff --git a/source/release-notes/v3.1-release-notes.rst b/source/release-notes/v3.1-release-notes.rst new file mode 100644 index 000000000..d7db53307 --- /dev/null +++ b/source/release-notes/v3.1-release-notes.rst @@ -0,0 +1,305 @@ +.. _v3.1-release-notes: + +v3.1 Release Notes +================== + +Administrative changes +---------------------- + +- `Breaking Changes`_ +- `Deprecations`_ +- `Dependency updates`_ +- `Upgrade directions`_ + +New Features +------------ + +- `Globus integration`_ +- `Path Selector widget`_ +- `Google Analytics 4 support`_ +- `Dynamic Checkboxes`_ +- `Disabling uploads and downloads`_ +- `Custom Javascript files`_ +- `Updated Apache options`_ +- `aarch64/arm64 and ppc64le packages`_ +- `Amazon Linux 2023 packages`_ +- `Debian 12 packages`_ + +Details of administrative changes +--------------------------------- + +Breaking Changes +................ + +User Settings File Change +************************* + +We had to change the location of the :ref:`user settings file ` +off of the ``DATAROOT`` which is cluster specific and problematic for sites that +have separate HOME directories for each cluster. + +The new default location is under the ``XDG_CONFIG_HOME``. This change was made +to accomidate sites that have separate HOME directories for each cluster. + +Sites who have never used this configuration do not need to do anything. + +Sites that have reconfigured the :ref:`user settings file ` +need to provide the full path for this file. It's recommended that you do not +use a path in the ``DATAROOT`` as that is cluster specific. + +Deprecations +............ + +RedHat/CentOS 7 packages deprecated +*********************************** + +OnDemand 3.1 will be the last OnDemand release to support RedHat/CentOS 7. + +Dependency updates +.................. + +This release updates the following dependencies: + +- Ruby 3.1 **(RHEL 8 & 9 only)** + + .. warning:: The change in Ruby version means any Ruby based apps that are not provided by the OnDemand RPM must be rebuilt or supply their own ``bin/ruby`` to use the older version of ruby. + +- NodeJS 18 **(All OSes except RHEL 7)** + + .. warning:: The change in Node version means any Node based apps that are not provided by the OnDemand RPM must be rebuilt. + +- Passenger 6.0.17 +- NGINX 1.22.1 +- ondemand-dex 2.36.0 +- mod_auth_openidc 2.4.14.1 (RHEL 7 & 8 only) + +Upgrade directions +.................. + +.. warning:: + + As always please update the *development* or *test* instances of OnDemand installed at your center first to test and verify before you modify the *production* instance. + +.. warning:: + + The OnDemand upgrade has only been tested going from 3.0.x to 3.1.x. + +#. Update OnDemand release RPM + + .. tabs:: + + .. tab:: RedHat/CentOS 7 + + .. code-block:: sh + + sudo yum install -y https://yum.osc.edu/ondemand/3.1/ondemand-release-web-3.1-1.el7.noarch.rpm + + + .. tab:: RedHat/Rocky Linux/AlmaLinux 8 + + .. code-block:: sh + + sudo yum install -y https://yum.osc.edu/ondemand/3.1/ondemand-release-web-3.1-1.el8.noarch.rpm + + .. tab:: RedHat/Rocky Linux/AlmaLinux 8 + + .. code-block:: sh + + sudo yum install -y https://yum.osc.edu/ondemand/3.1/ondemand-release-web-3.1-1.el9.noarch.rpm + + .. tab:: Ubuntu 20.04 + + .. code-block:: sh + + wget -O /tmp/ondemand-release-web_3.1.0-focal_all.deb https://apt.osc.edu/ondemand/3.1/ondemand-release-web_3.1.0-focal_all.deb + sudo apt install /tmp/ondemand-release-web_3.1.0-focal_all.deb + sudo apt update + + .. tab:: Ubuntu 22.04 + + .. code-block:: sh + + wget -O /tmp/ondemand-release-web_3.1.0-jammy_all.deb https://apt.osc.edu/ondemand/3.1/ondemand-release-web_3.1.0-jammy_all.deb + sudo apt install /tmp/ondemand-release-web_3.1.0-jammy_all.deb + sudo apt update + +#. Enable dependencies + + **RHEL/Rocky/AlmaLinux 8 & 9 only** + + .. code-block:: sh + + sudo dnf module reset nodejs + sudo dnf module enable nodejs:18 + sudo dnf module reset ruby + sudo dnf module enable ruby:3.1 + +#. Update OnDemand + + .. tabs:: + + .. tab:: yum/dnf + + .. code-block:: sh + + sudo yum clean all + sudo yum update ondemand + + + .. tab:: apt + + .. code-block:: sh + + sudo apt-get --only-upgrade install ondemand + +#. (Optional) If using Dex based authentiction, update the ``ondemand-dex`` package. + + .. tabs:: + + .. tab:: yum/dnf + + .. code-block:: sh + + sudo yum update ondemand-dex + + + .. tab:: apt + + .. code-block:: sh + + sudo apt-get --only-upgrade install ondemand-dex + +#. Update Apache configuration and restart Apache. + + .. code-block:: sh + + sudo /opt/ood/ood-portal-generator/sbin/update_ood_portal + + .. tabs:: + + .. tab:: RedHat/CentOS 7 + + .. code-block:: sh + + sudo systemctl try-restart httpd24-httpd.service + + .. tab:: RedHat/Rocky Linux/AlmaLinux 8 & 9 + + .. code-block:: sh + + sudo systemctl try-restart httpd + + .. tab:: Ubuntu 20.04 & 22.04 + + .. code-block:: sh + + sudo systemctl try-restart apache2 + +#. (Optional) If ``ondemand-dex`` was installed, restart the ``ondemand-dex`` service. + + .. code-block:: sh + + sudo systemctl try-restart ondemand-dex.service + +#. (Optional) If ``ondemand-selinux`` was installed, see :ref:`ood_selinux_updates` + +#. Force all PUNs to restart + + .. code-block:: sh + + sudo /opt/ood/nginx_stage/sbin/nginx_stage nginx_clean -f + +Details of new features +----------------------- + +Globus integration +.................. + +The files application will now provide a link to Globus endpoints +when users navigate to a directory that is within that endpoint. + +Administrators need to configure OnDemand to map directories +to Globus endpoints. Refer to the +:ref:`configuration entry for enabling globus endpoints `. + +Path Selector widget +.................... + +Open OnDemand now ships it's own ``path_selector`` form widet. +This replaces the library at https://github.com/osc/bc_js_filepicker +for centers that have or do use this library. + +You can go here to find :ref:`details on the path selector `. + +Google Analytics 4 support +.......................... + +Google Analytics has updated since version 3.0 and 3.1 has support now for +this update. + +Refer to the :ref:`google analytics configuration ` +for how to configure this. + +Dynamic Checkboxes +.................. + +``check_box`` form widgets can now be used with dynamic ``data-set`` and +``data-hide`` directives. + +Refer to :ref:`dynamic-bc-apps` for more details. + +Disabling uploads and downloads +............................... + +Sites can now disable uploads and downloads through the file +browser. See the configuration for :ref:`disabling downloads ` +and :ref:`disabling uploads ` for how to configure this. + +Custom Javascript files +....................... + +Sites can now add custom javascript files that will get loaded on every +page of the dashboard application. Refer to the +:ref:`custom_javascript_files configuration property ` +for more information. + +Support added for completed.{md,html}.erb +......................................... + +Sites can now add a ``completed.{md,html}.erb`` to interactive applications +to display information on the session's card when the job has completed. + +See :ref:`bc_completed_html_md_erb` for more information. + +Updated Apache options +...................... + +We've updated ``ood_portal.yml`` for two common apache configurations +sites may wish to enable. + +The first is to :ref:`disable apache logging ` in favor of +supplying a global log configuration in a seperate file. + +The second is to alllow for custom directives. You can now supply +:ref:`custom location directives ` +and :ref:`custom virtual host directives `. + +aarch64/arm64 and ppc64le packages +.................................. + +Added aarch64/arm64 and ppc64le packages for some operating systems. +See :ref:`Supported Operating Systems and Architectures ` +for a full list of which operating systems support aarch64 and ppc64le. + + +Amazon Linux 2023 packages +.......................... + +Added Amazon Linux 2023 packages. +See :ref:`install-software` for installation instructions. + +Debian 12 packages +.................. + +Added Debian 12 packages. +See :ref:`install-software` for installation instructions. diff --git a/source/requirements.rst b/source/requirements.rst index a5d2ff10e..bd2a85997 100644 --- a/source/requirements.rst +++ b/source/requirements.rst @@ -8,13 +8,22 @@ Supported Operating Systems .. _os-support: -At this time OnDemand only supports the following operating systems: - -- RedHat/CentOS 7 -- RedHat/Rocky Linux/AlmaLinux 8 -- RedHat/Rocky Linux/AlmaLinux 9 -- Ubuntu 20.04 -- Ubuntu 22.04 +At this time OnDemand only supports the following operating systems and architectures: + +.. role:: raw-html(raw) + :format: html + +.. csv-table:: Operating System and Architecture Support + :header: "","x86_64","aarch64/arm64","ppc64le" + :stub-columns: 1 + + "RedHat/CentOS 7",:raw-html:`✅`,:raw-html:`✅`,:raw-html:`✅` + "RedHat/Rocky Linux/AlmaLinux 8",:raw-html:`✅`,:raw-html:`✅`,:raw-html:`✅` + "RedHat/Rocky Linux/AlmaLinux 9",:raw-html:`✅`,:raw-html:`✅`,:raw-html:`✅` + "Ubuntu 20.04",:raw-html:`✅`,:raw-html:`✅`,:raw-html:`❌` + "Ubuntu 22.04",:raw-html:`✅`,:raw-html:`✅`,:raw-html:`❌` + "Debian 12",:raw-html:`✅`,:raw-html:`✅`,:raw-html:`✅` + "Amazon Linux 2023",:raw-html:`✅`,:raw-html:`✅`,:raw-html:`❌` Software Requirements --------------------- diff --git a/source/tutorials/tutorials-dashboard-apps.rst b/source/tutorials/tutorials-dashboard-apps.rst new file mode 100644 index 000000000..6f6d47873 --- /dev/null +++ b/source/tutorials/tutorials-dashboard-apps.rst @@ -0,0 +1,20 @@ +.. _app-development-tutorials-dashboard-apps: + +Developing The OOD Dashboard +============================ + +.. warning:: + :ref:`enabling-development-mode` must be completed first for this tutorial to work. + +Open OnDemand is composed of several apps, one of which is the ``dashboard`` app. +You can see some of the other apps that make up OOD `here. `__ + +This tutorial aims to equip admins with the knowledge and tools for developing the Open OnDemand +``dashboard`` and ``shell`` apps directly from *within* OnDemand itself. + +.. toctree:: + :maxdepth: 2 + :caption: Tutorials + + tutorials-dashboard-apps/dashboard + tutorials-dashboard-apps/shell-app diff --git a/source/tutorials/tutorials-dashboard-apps/dashboard.rst b/source/tutorials/tutorials-dashboard-apps/dashboard.rst new file mode 100644 index 000000000..754ea6549 --- /dev/null +++ b/source/tutorials/tutorials-dashboard-apps/dashboard.rst @@ -0,0 +1,145 @@ +.. _app-development-tutorials-dashboard-apps-dashboard: + +Developing the Dashboard App +============================ + +.. warning:: + You muse have followed :ref:`enabling-development-mode` for any part of this tutorial to work. + +Things To Know +-------------- + +We are going to be using ``bundler`` through a script which comes with OOD located in the root of the +dashboard at ``bin/setup``. What this will do for us is essentially run ``bundler`` and ``npm`` to ensure +are environment is correct. This is all being pulled from the dashboard ``Gemfile``. You could, in theory, +add whatever you like to this ``Gemfile`` and rebuild OOD with that new gem for development work, as an +example. + +Also, it is recommended to set this to your local app environment so that ``bundler`` does not try and install +the gems on the system, as unlike ``npm`` which starts builds locally by default, ``bundler`` attempts +system installs by default. + +Create a Dev Dashboard +---------------------- +#. ``clone`` the OOD repo into: ``cd ~/ondemand/misc`` then ``git clone git@github.com:OSC/ondemand.git`` +#. Work out of the ``dev`` directory/space: ``cd ~/ondemand/dev/``. +#. Symlink to the ``dashboard`` app in the cloned repo: ``ln -s ../misc/ondemand/apps/dashboard/dashboard/ dashboard`` +#. Make a branch and to begin word on your dev dashboard: ``git checkout -b dev_work`` +#. Rebuild the ood dashboard app: ``bin/setup``. +#. Navigate to the Sandbox and launch your ``dashboard`` app to use the ``dev_work``. + +Notice the ``url`` for this ``/pun/dev/dashboard`` app. No longer do +you see ``/pun/sys/dashboard/`` but instead ``/pun/dev/dashboard/``. + +Add ``.env.local`` File +----------------------- +Now that we have a our dev dashboard running, a good first step is to next ensure it +looks different from the production dashboard. This will help ensure not ending up in the wrong tab, +using ``sys/dashboard`` instead of ``dev/dashboard``, and possibly causing confusion. + +Use an editor or IDE and do the following: + +.. code-block:: sh + + cd ~/ondemand/dev/dashboard + touch .env.local + vim .env.local + +The idea here is to make sure the dev dashboard *looks* different so we don't have to check that ``url`` in the +browser to know which dashboard we are in. + +Inside the ``.env.local`` we can add an environment variable to change the color of the dev dashboard like so: + +.. code-block:: sh + + # .env.local file + OOD_BRAND_BG_COLOR='grey' + +Now click the ``Develop`` dropdown menu on the upper right corner and click ``Restart Web Server``. After a few moments +you should now see the dashboard with a grey background in the banner. This will help to distinguish your dev +environment from the production. + + +.. figure:: ../../images/develop_dashboard_grey_background.png + :align: center + + Different banner color for the dev dashboard + + +Set Dev Configuration Directory +------------------------------- +Our dev dashboard is still using the same configuration files as the system dashboard, but we can change this. + +Go back into ``.env.local`` and set a new path for *the dev dashboard to pick up its own +configurations* using the ``OOD_CONFIG_D_DIRECTORY`` environment variable like so: + +.. code-block:: sh + + # .env.local file + OOD_CONFIG_D_DIRECTORY="~/ondemand/dev/dashboard/config/ondemand.d/" + +We need to *restart the PUN when we add or change environment variables* with ``bin/setup``. + +Add Dev Configurations +---------------------- +Now, we can begin to set our own configurations in our new ``ondemand.d`` directory for +the dev dashboard and see the changes. Let's add some configs to our dev dashboard to get +an idea what can be done and play with the layout. + +We will add ``pinned_apps`` to our dev dashboard as an example to see how this works. + +Create a file in the ``~/ondemand/dev/dashboard/config/ondemand.d/`` directory named ``ondemand.yml`` then +open the file and add the following: + +.. code-block:: yaml + + pinned_apps: + - sys/* + pinned_apps_menu_length: 4 + pinned_apps_group_by: category + +Assuming youre restarted the PUN when you set the new config directory above, you *should* be able to simply +refresh the browser and see the new pinned apps layout take effect. If not though, simply restart the PUN +as usual to force the changes. + +.. figure:: ../../images/develop_dashboard_pinned_apps.png + :align: center + + Dev dashboard with its own pinned apps configuration + +Now, we can begin to add other configurations to this new ``ondemand.yml`` and keep restarting +the PUN to see our changes. + +This is a great way to test out new features, or play with any features you may be interested in with OOD before +making the changes in production or spinning up a whole dev environment with a VM. + +At this point you have all the pieces needed to use the :ref:`customizations` page and play with those changes +in your dev dashboard. + +But, what if we want to add something to Open OnDemand? + +Develop OOD in OOD +------------------ +With all the above in place, you can also begin to add features and functionality to OOD in this development +setting to then see how this will actually run and work. + +Suppose you see a feature being worked on in the OOD repo on the branch ``new_feature``. How could you pull +this work down and see its current state while also trying to build it out? + +First, launch the ``shell`` and go into your dev ``dashboard`` root then: + +#. ``git pull`` +#. ``git checkout new_feature`` +#. ``bin/setup`` + +After the build you now have the feature ready to be worked right there in your dev dashboard. + +Go ahead and enter you Sandbox and launch the dev dashboard. What you are in once that is done is the current +state the feature is in. + +If you are not making any changes to the configurations, as the steps above mostly do, then each change to the code +simply requires page refreshes to see the feature work. + + + + diff --git a/source/tutorials/tutorials-dashboard-apps/shell-app.rst b/source/tutorials/tutorials-dashboard-apps/shell-app.rst new file mode 100644 index 000000000..e36c0ca9a --- /dev/null +++ b/source/tutorials/tutorials-dashboard-apps/shell-app.rst @@ -0,0 +1,50 @@ +.. _app-development-tutorials-dashboard-apps-shell-app: + +Developing the Shell App +======================== + +The ``shell`` app is significantly different from the dashboard app. It is purely a ``node.js`` app. +This means that we only need to use ``npm`` to build and do dev work. + +Create a Dev Shell +------------------ +#. ``clone`` the OOD repo into: ``cd ~/ondemand/misc`` then ``git clone git@github.com:OSC/ondemand.git`` +#. Work out of the ``dev`` directory/space: ``cd ~/ondemand/dev/``. +#. Symlink to the ``shell`` app in the cloned repo: ``ln -s ../misc/ondemand/apps/dashboard/shell/ shell`` +#. Make a branch and to begin word on your dev dashboard: ``git checkout -b dev_work`` +#. Rebuild the ``shell`` app: ``bin/setup``. +#. Navigate to the Sandbox and launch your dev ``shell`` app to use the ``dev_work`` branch. + +Notice the ``url`` for this app. No longer do you see ``*/sys/shell`` but instead ``*/dev/shell``. + +Build Old Version of Shell +.......................... + +#. pull down ondemand in ``~/ondemand/misc`` +#. then list versions with ``git tags`` +#. run ``git checkout `` +#. now make a branch with your changes and use ``bin/setup`` to rebuild if needed + +Then for the **shell app** from a login terminal run: + +#. ``cd dev`` +#. ``ln -s ../misc/ondemand/apps/dashboard/shell/ shell-18`` + +And then step into that symlinked directory and run: +#. ``bin/setup`` + +If you go start this app from sandbox you'll notice a different url than before, +showing you are in a dev shell: ``pun/dev/shell-1.8`` + +Issues and Errors +................. +Ensure you are using the correct version of Node when you go to build using ``nvm`` if possible. Sometimes +this can be set automatically for you in your ``.bashrc`` so just ensure you are on the version you should +be when you run ``bin/setup``. + + +Develop the Shell +----------------- + +At this point we have a working dev ``shell`` and can start to make changes to this code and issue rebuilds +for ``npm`` with ``bin/setup`` when needed. \ No newline at end of file