cylc · kinow · Aug 31, 2021 · May 11, 2021 · May 17, 2021 · May 18, 2021
diff --git a/.coveragerc b/.coveragerc
@@ -29,8 +29,7 @@ omit =
     venv/*
     cylc/uiserver/tests/*
     cylc/uiserver/websockets/*
-    cylc/uiserver/config_defaults.py
-    setup.py
+    cylc/uiserver/jupyter*_config.py
 parallel = True
 plugins=
 include=
@@ -53,8 +52,7 @@ omit =
     venv/*
     cylc/uiserver/tests/*
     cylc/uiserver/websockets/*
-    cylc/uiserver/config_defaults.py
-    setup.py
+    cylc/uiserver/jupyter*_config.py
 precision=2
 show_missing=False
 skip_covered=False

diff --git a/CHANGES.md b/CHANGES.md
@@ -10,6 +10,17 @@ creating a new release entry be sure to copy & paste the span tag with the
 `actions:bind` attribute, which is used by a regex to find the text to be
 updated. Only the first match gets replaced, so it's fine to leave the old
 ones in. -->
+
+-------------------------------------------------------------------------------
+## __cylc-uiserver-0.6.0 (<span actions:bind='release-date'>Released 2021-??-??</span>)__
+
+Multi-user functionality implented.
+
+### Enhancements
+
+[#230](https://github.com/cylc/cylc-uiserver/pull/230) -
+Convert the UI Server to a jupyter_server extension
+
 -------------------------------------------------------------------------------
 ## __cylc-uiserver-0.5.0 (<span actions:bind='release-date'>Released 2021-07-28</span>)__
 

diff --git a/README.md b/README.md
@@ -1,22 +1,21 @@
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/cylc-uiserver/badges/version.svg)](https://anaconda.org/conda-forge/cylc-uiserver)
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/cylc-uiserver/badges/downloads.svg)](https://anaconda.org/conda-forge/cylc-uiserver)
+[![PyPI](https://img.shields.io/pypi/v/cylc-uiserver.svg?color=yellow)](https://pypi.org/project/cylc-uiserver/)
+[![forum](https://img.shields.io/discourse/https/cylc.discourse.group/posts.svg)](https://cylc.discourse.group/)
 [![Test](https://github.com/cylc/cylc-uiserver/actions/workflows/test.yml/badge.svg?branch=master&event=push)](https://github.com/cylc/cylc-uiserver/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/cylc/cylc-uiserver/branch/master/graph/badge.svg)](https://codecov.io/gh/cylc/cylc-uiserver)
 
+
 # Cylc UI Server
 
-This project contains the Cylc UI Server. A JupyterHub-compatible application,
+This project contains the Cylc UI Server which provides the Cylc GUI
 used to serve the Cylc UI, and to communicate with running Cylc Schedulers.
 
 [Cylc Website](https://cylc.org/) |
 [Contributing](CONTRIBUTING.md) |
-[Developing](DEVELOPING.md)
-
-## Contents
+[Developing](#Developing) |
+[Forum](https://cylc.discourse.group/)
 
-- [Installation](#installation)
-- [Introduction](#introduction)
-- [Copyright](#copyright-and-terms-of-use)
 
 ## Introduction
 
@@ -25,24 +24,37 @@ interface.
 
 This repository provides the following components of the Cylc system.
 
-* The UI
+* **The UI**
 
   This is the Cylc web app that provides control and monitoring functionalities
   for Cylc workflows.
 
-* The UI Server
+  > The UI is developed in a separate repository https://github.com/cylc/cylc-ui
+
+* **The UI Server**
 
   This is a web server which serves the Cylc web UI. It connects to running
   workflows and workflow databases to provide the information the UI displays.
+  It is a [Jupyter Server](https://github.com/jupyter-server/jupyter_server).
 
-* The Hub
+* **The Hub**
+
+  In multi-user setups this launches UI Servers, provides a proxy for running
+  server and handles authentication. It is a
+  [JupyterHub](https://github.com/jupyterhub/jupyterhub) server.
 
-  This launches UI Servers, provides a proxy for running server and handles
-  authentication. It is a JupyterHub server.
 
 ## Installation
 
-For production:
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/cylc-uiserver/badges/version.svg)](https://anaconda.org/conda-forge/cylc-uiserver)
+[![PyPI](https://img.shields.io/pypi/v/cylc-uiserver.svg?color=yellow)](https://pypi.org/project/cylc-uiserver/)
+![Conda-Platforms](https://img.shields.io/conda/pn/conda-forge/cylc-uiserver)
+
+For more information on the Cylc components and full-stack Cylc installations
+see the
+[Cylc documentation](https://cylc.github.io/cylc-doc/latest/html/installation.html).
+
+### For Single-User Setups
 
 ```console
 # via conda (preferred)
@@ -52,13 +64,56 @@ $ conda install cylc-uiserver
 $ pip install cylc-uiserver
 ```
 
-## Running
+### For Multi-User Setups
 
 ```console
-$ cylc hub
+# via conda (preferred)
+$ conda install cylc-uiserver-hub
+
+# via pip (consult jupyterhub documentation)
+$ pip install cylc-uiserver[hub]
+```
+
+
+## Running
+
+The Cylc UIServer is a
+[Jupyter Server](https://github.com/jupyter-server/jupyter_server)
+extension (like [JupyterLab](https://github.com/jupyterlab/jupyterlab)).
+
+### For Single-User Setups
+
+Run as a standalone server using a URL token for authentication:
+
+```bash
+# launch the Cylc GUI and open a browser tab
+cylc gui
+
+# alternatively the same app can be opened with the jupyter command
+$ jupyter cylc
 ```
 
-The default URL is [http://localhost:8000](http://localhost:8000).
+> By default authentication is provided by the URL token, alternatively a
+> password can be configured (see Jupyter Server docs).
+>
+> There is no per-user authorisation so anyone who has the URL token has full
+> access to the server.
+
+### For Multi-User Setups
+
+Run a central [JupyterHub](https://github.com/jupyterhub/jupyterhub) server
+under a user account with the privileges required to spawn `cylc` processes as
+other users.
+
+```bash
+# launch the Cylc Hub
+# (the default URL is http://localhost:8000)
+cylc hub
+```
+
+> Users then authenticate with the hub which launches and manages their UI
+> Server.
+
 
 ## Configuring
 
@@ -70,20 +125,20 @@ The Cylc Hub will load the following files in order:
 
    These are the Cylc defaults which are hardcoded within the repository.
 
-   (`<python-installation>/cylc/uiserver/config_defaults.py`)
+   (`<python-installation>/cylc/uiserver/jupyter_config.py`)
 
 2) Site Config
 
    This file configures the Hub/UIS for all users. The default path can be
    changed by the ``CYLC_SITE_CONF_PATH`` environment variable.
 
-   (`/etc/cylc/hub/config.py`)
+   (`/etc/cylc/hub/jupyter_config.py`)
 
 3) User Config
 
    This file
 
-   (`~/.cylc/hub/config.py`)
+   (`~/.cylc/hub/jupyter_config.py`)
 
 Alternatively a single config file can be provided on the command line.
 
@@ -96,30 +151,57 @@ $ cylc hub --config
 > If specifying a config file on the command line the system config containing
 > the hardcoded Cylc default will **not** be loaded.
 
+> **Note:**
+>
+> The hub can also be run using the ``jupyterhub`` command, however, you
+> must source the configuration files manually on the command line.
+
 See the Jupyterhub documentation for details on configuration options.
 
 ### UI Server
 
-The UI Server is (currently) also configured from the same configuration file(s)
-as the hub using the
-`UIServer` namespace.
+The UI Server is also configured from the same configuration file(s) as the hub
+using the `UIServer` namespace.
 
 Currently the UI Server accepts these configurations:
 
-* `c.UIServer.ui_build_dir`
-* `c.UIServer.ui_version`
-* `c.UIServer.logging_config`
-* `c.UIServer.scan_iterval`
+* `c.CylcUIServer.ui_build_dir`
+* `c.CylcUIServer.ui_version`
+* `c.CylcUIServer.scan_iterval`
+
+See the `cylc.uiserver.app.UIServer` file for details.
+
+The Cylc UI Server is a
+[Jupyter Server](https://github.com/jupyter-server/jupyter_server) extension.
+Jupyter Server can run multiple extensions. To control the extensions that
+are run use the `ServerApp.jpserver_extensions` configuration, see the 
+[Jupyter Server configuration documentation](https://jupyter-server.readthedocs.io/en/latest/other/full-config.html#other-full-config).
+
+### UI
+
+The UI can be configured via the "Settings" option in the Dashboard.
+
+Currently these configurations are stored in the web browser so won't travel
+around a network and might not persist.
 
-See the `cylc.uiserver.main.UIServer` file for details.
 
 ## Developing
 
-1) Read the [Contributing](CONTRIBUTING.md) page.
+[![Contributors](https://img.shields.io/github/contributors/cylc/cylc-uiserver.svg?color=9cf)](https://github.com/cylc/cylc-uiserver/graphs/contributors)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/cylc/cylc-uiserver.svg?color=yellowgreen)](https://github.com/cylc/cylc-uiserver/commits/master)
+[![Last commit](https://img.shields.io/github/last-commit/cylc/cylc-uiserver.svg?color=ff69b4)](https://github.com/cylc/cylc-uiserver/commits/master)
+
+Contributions welcome:
 
-2) Fork and clone this repo.
+* Read the [contributing](CONTRIBUTING.md) page.
+* Development setup instructions are in the
+  [developer docs](https://cylc.github.io/cylc-admin/#cylc-8-developer-docs).
+* Involved change proposals can be found in the
+  [admin pages](https://cylc.github.io/cylc-admin/#change-proposals).
+* Touch base in the
+  [developers chat](https://matrix.to/#/#cylc-general:matrix.org).
 
-3) Install from source into your Python environment:
+1) Install from source into your Python environment:
 
    ```console
    $ pip install -e .[all]
@@ -130,12 +212,14 @@ See the `cylc.uiserver.main.UIServer` file for details.
    > If you want to run with a development copy of Cylc Flow you must install
    > it first else `pip` will download the latest version from PyPi.
 
-4) For UI development set the following configuration to use your UI build
+2) For UI development follow the developer instructions for the
+   [cylc-ui](https://github.com/cylc/cylc-ui) project, then
+   set the following configuration so Cylc uses your UI build
    (rather than the default bundled UI build):
 
    ```python
-   # ~/.cylc/hub/config.py
-   c.UIServer.ui_build_dir = '~/cylc-ui/dist'  # path to build
+   # ~/.cylc/hub/jupyter_config.py
+   c.CylcUIServer.ui_build_dir = '~/cylc-ui/dist'  # path to build
    ```
 
 ## Copyright and Terms of Use
@@ -148,7 +232,7 @@ either version 3 of the License, or (at your option) any later version.
 
 Cylc is distributed in the hope that it will be useful, but WITHOUT ANY
 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License along with
-Cylc.  If not, see [GNU licenses](http://www.gnu.org/licenses/).
+Cylc. If not, see [GNU licenses](http://www.gnu.org/licenses/).
diff --git a/cylc/uiserver/scripts/uis.py → conftest.py b/cylc/uiserver/scripts/uis.py → conftest.py
@@ -12,18 +12,13 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
-"""cylc uis
 
-Launch a Cylc UI Server.
+pytest_plugins = [
+    'jupyter_server.pytest_plugin'
+]
 
-This is an internal command invoked by the Cylc Hub via the configured
-Jupyterhub spawner.
-"""
 
-from cylc.uiserver.main import main as uis_main
-
-INTERNAL = True
-
-
-def main(*_):
-    uis_main()
+def pytest_ignore_collect(path):
+    # --doctest-modules seems to ignore the value if configured in pyproject
+    if 'jupyter_config.py' in str(path):
+        return True
diff --git a/cylc/uiserver/__init__.py b/cylc/uiserver/__init__.py
@@ -14,3 +14,18 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 __version__ = "0.5.0"
+
+from cylc.uiserver.app import CylcUIServer
+
+
+def _jupyter_server_extension_points():
+    """
+    Returns a list of dictionaries with metadata describing
+    where to find the `_load_jupyter_server_extension` function.
+    """
+    return [
+        {
+            "module": "cylc.uiserver.app",
+            'app': CylcUIServer
+        }
+    ]