Jupyter server #230
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,22 +1,21 @@ | ||
| [](https://anaconda.org/conda-forge/cylc-uiserver) | ||
| [](https://anaconda.org/conda-forge/cylc-uiserver) | ||
| [](https://pypi.org/project/cylc-uiserver/) | ||
| [](https://cylc.discourse.group/) | ||
| [](https://github.com/cylc/cylc-uiserver/actions/workflows/test.yml) | ||
| [](https://codecov.io/gh/cylc/cylc-uiserver) | ||
|
|
||
|
|
||
| # Cylc UI Server | ||
|
|
||
| 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) | | ||
| [Forum](https://cylc.discourse.group/) | ||
|
|
||
|
|
||
| ## Introduction | ||
|
|
||
|
|
@@ -25,24 +24,37 @@ interface. | |
|
|
||
| This repository provides the following components of the Cylc system. | ||
|
|
||
| * **The UI** | ||
|
|
||
| This is the Cylc web app that provides control and monitoring functionalities | ||
| for Cylc workflows. | ||
|
|
||
| > 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). | ||
|
There was a problem hiding this comment. A Jupyter Server application, or a Jupyter web Application? I'm reading their docs, from what I understood, Jupyter Server is the utility code for creating applications or extensions. Applications being complete web applications that use the Jupyter Server, and Extensions only extend the REST API. There was a problem hiding this comment. Huh, so looks like everything is an extension, but there's a special There was a problem hiding this comment. So there's some similar but different terminology here which makes things confusing. The Cylc UI Server (as of this PR) is a "Jupyter Server extension applicaiton".
Extension applications can:
Jupyter server also offers non-configurable extensions (ones which aren't applications), these are cruder. This page helps show the difference - https://jupyter-server.readthedocs.io/en/latest/developers/extensions.html |
||
|
|
||
| * **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. | ||
|
|
||
|
|
||
| ## Installation | ||
|
|
||
| [](https://anaconda.org/conda-forge/cylc-uiserver) | ||
| [](https://pypi.org/project/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 | ||
| ``` | ||
|
|
||
| ### For Multi-User Setups | ||
|
|
||
| ```console | ||
| # 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)). | ||
|
There was a problem hiding this comment. Ah, I guess it's an extension then, I thought it was an application 👍 There was a problem hiding this comment. If splitting hairs it is technically an "extension application"! From the users perspective the difference between an "extension" and an "extension application" is invisible. There was a problem hiding this comment. Brilliant, thanks @oliver-sanders ! It was more so I knew the correct term in case I needed to report an issue upstream, or talk to someone else about Jupyter Server. But extension application is quite a mouthful, I'll probably just use jupyter server, or jupyter server app, or whichever my 🧠 picks first. Leaving unresolved in case others are interested in this answer too. |
||
|
|
||
| ### 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 | ||
| ``` | ||
|
|
||
| > 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/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/jupyter_config.py`) | ||
|
|
||
| 3) User Config | ||
|
|
||
| This file | ||
|
|
||
| (`~/.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 also configured from the same configuration file(s) as the hub | ||
| using the `UIServer` namespace. | ||
|
|
||
| Currently the UI Server accepts these configurations: | ||
|
|
||
| * `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. | ||
|
|
||
|
|
||
| ## Developing | ||
|
|
||
| [](https://github.com/cylc/cylc-uiserver/graphs/contributors) | ||
| [](https://github.com/cylc/cylc-uiserver/commits/master) | ||
| [](https://github.com/cylc/cylc-uiserver/commits/master) | ||
|
|
||
| Contributions welcome: | ||
|
|
||
| * 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). | ||
|
|
||
| 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. | ||
|
|
||
| 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/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. | ||
|
|
||
| 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/). | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
https://cylc.org/ currently forwards to https://niwa.co.nz/
I'm guessing this will be fixed by production time but thought I'd flag it now.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ping @hjoliver
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, that's changed recently it used to redirect to GH pages, yikes!
Hmmm, I've seen this error before, I think my rebase of the cylc-ui branch might not have been fully successful.