add docs to develop dashboard and shell apps within ood itself (#912)

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

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. <https://github.com/OSC/ondemand/tree/master/apps>`__
+
+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

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 [email protected]: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.
+
+
+
+

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 [email protected]: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 <version>`` 
+#. 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.