From 67256388acf6383ae6c0d75617deffeebfe97b5d Mon Sep 17 00:00:00 2001 From: "Bruno P. Kinoshita" Date: Fri, 9 Aug 2019 11:39:14 +1200 Subject: [PATCH] Update readme file --- README.md | 105 ++++++++---------------------------------------------- 1 file changed, 14 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 377950fd..b0dad4f7 100644 --- a/README.md +++ b/README.md @@ -1,103 +1,30 @@ [![Build Status](https://travis-ci.org/cylc/cylc-uiserver.svg?branch=master)](https://travis-ci.org/cylc/cylc-uiserver) [![codecov](https://codecov.io/gh/cylc/cylc-uiserver/branch/master/graph/badge.svg)](https://codecov.io/gh/cylc/cylc-uiserver) -# Running Cylc with JupyterHub +# Cylc UI Server -_This is a Work-In-Progress_ +This project contains the Cylc UI Server. A JupyterHub-compatible application, +used to display the Cylc UI (or simply UI) to users, and to communicate with +Workflow Services (WFS). -## Installing requirements +## Installation -```shell -$ virtualenv venv -Using base prefix '/home/kinow/Development/python/anaconda3' -New python executable in /home/kinow/Development/python/workspace/cylc-jupyterhub/venv/bin/python -Installing setuptools, pip, wheel... -done. -$ . venv/bin/activate -(venv) $ pip install -e . -... -... -Installing collected packages: tornado, prometheus-client, chardet, idna, certifi, urllib3, requests, pamela, async-generator, python-oauth2, six, python-dateutil, SQLAlchemy, MarkupSafe, Mako, python-editor, alembic, jinja2, ipython-genutils, decorator, traitlets, jupyterhub, cylc-jupyterhub - Running setup.py develop for cylc-jupyterhub -Successfully installed Mako-1.0.7 MarkupSafe-1.1.1 SQLAlchemy-1.2.18 alembic-1.0.7 async-generator-1.10 certifi-2018.11.29 chardet-3.0.4 cylc-jupyterhub decorator-4.3.2 idna-2.8 ipython-genutils-0.2.0 jinja2-2.10 jupyterhub-0.9.4 pamela-1.0.0 prometheus-client-0.6.0 python-dateutil-2.8.0 python-editor-1.0.4 python-oauth2-1.1.0 requests-2.21.0 six-1.12.0 tornado-5.1.1 traitlets-4.3.2 urllib3-1.24.1 -(venv) $ npm install -g configurable-http-proxy -/home/kinow/.nvm/versions/node/v11.6.0/bin/configurable-http-proxy -> /home/kinow/.nvm/versions/node/v11.6.0/lib/node_modules/configurable-http-proxy/bin/configurable-http-proxy -+ configurable-http-proxy@4.0.1 -added 45 packages from 62 contributors in 5.53s -(venv) $ jupyterhub --version -0.9.4 -(venv) $ configurable-http-proxy --version -4.0.1 -(venv) $ cylc-uiserver -usage: cylc-uiserver [-h] [-p PORT] -s STATIC -cylc-uiserver: error: the following arguments are required: -s/--static -``` +To install the production version, run: -We can start the hub with: `(venv) $ jupyterhub`, and navigate to [http://localhost:8000](http://localhost:8000). +- `pip install cylc-uiserver` -This starts a JupyterHub instance, with the authenticator **jupyterhub.auth.PAMAuthenticator**, -and the spawner **jupyterhub.spawner.LocalProcessSpawner**. Look at the file `jupyterhub_config.py` -in this repository to confirm the spawner used, and the parameters passed. These parameters define -the directory of static content, and also what is the command that the spawner in JupyterHub must -use (`cylc-uiserver`). +And for the development version, run the following from a clone of the project +git repository. -## Configuration +- `pip install -e .` -```bash -(venv) $ jupyterhub --generate-config -Writing default config to: jupyterhub_config.py -(venv) $ jupyterhub -f $(pwd -P)/jupyterhub_config.py -``` - -By default we have `jupyterhub.spawner.LocalProcessSpawner` as the spawner. It invokes -a bash shell that executes `jupyterhub-singleuser` with some parameters given via command -line and environment variables. - -In order to have JupyterHub spawning our Cylc UI server, which is initialized by `cylc-uiserver`, -we have to add the following settings in `jupyterhub_config.py`: - -``` -# not necessary as the default, but good nonetheless -c.JupyterHub.spawner_class = 'jupyterhub.spawner.LocalProcessSpawner' -c.Spawner.args = ['-s', '../cylc-web/dist/'] -c.Spawner.cmd = ['cylc-uiserver'] -``` - -The `LocalProcessSpawner` will add `--port` with a random generated port number by default. The -`c.Spawner.args` includes an extra `-s ../cylc-web/dist`, which is the location where we should -find the application `index.html` (change for your environment if necessary). - -Also note that the `c.Spawner.cmd` is `cylc-uiserver`, which is put in the `$PATH` as part of -the instructions of the `setup.py` in this repository. - -### Authentication - -We are after the scenario where a user A can start the UI server, and another user B is able -to access it too. - -With the default authenticator, `jupyterhub.auth.PAMAuthenticator`, if A starts the server, -B is not even able to authenticate to the running hub. That is because in Linux PAM has -restrictions in place, and you must be a super user, or wheel member, in order to use it. - -But if you start the hub as the root user, in a location that other users can access the files -(i.e. do not start under `/root`, use something like `/opt` and watch out for _selinux_), -then you should be able to get all users in the local system authenticating fine. - -### Authorization - -Once authenticated, the authorization is handled in the UI server. In the vanilla installation, -Jupyter Notebook would find the Cookie of the logged in user, and then query the Hub about it. -As we do not have the notebook, the example from Cylc Spawner 01 should work. - -It should work means that all users see each others UI servers. - -TODO: explain whether we can use the Hub REST API and DB scheme for Cylc workflow services -authentication. +Once that is done, the Hub can be started with `jupyterhub`. +The default URL is [http://localhost:8000](http://localhost:8000). ### Starting multiple instances of jupyterhub -If you need to run multiple instances of `jupyterhub`, you will have to follow the steps described -below: +If you need to run multiple instances of `jupyterhub`, you will have to follow +the steps described below: - copy `jupyterhub_config.py` to a different location - change the following settings (change the ports to your environment): @@ -106,7 +33,3 @@ below: * `c.JupyterHub.proxy_api_port = 9001` - finally start `jupyterhub` using that configuration file -## Services - -Q: Would Cylc Review be a service? Perhaps we could choose whether to start it with -the UI server or not!