update README

README.md

@@ -1,5 +1,7 @@
 [![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)
 
@@ -11,14 +13,8 @@ used to serve the Cylc UI, and to communicate with running Cylc Schedulers.
 
 [Cylc Website](https://cylc.org/) |
 [Contributing](CONTRIBUTING.md) |
-[Developing](#Developing)
-
-
-## Contents
-
-- [Installation](#installation)
-- [Introduction](#introduction)
-- [Copyright](#copyright-and-terms-of-use)
+[Developing](#Developing) |
+[Forum](https://cylc.discourse.group/)
 
 
 ## Introduction
@@ -33,6 +29,8 @@ This repository provides the following components of the Cylc system.
   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
@@ -48,10 +46,15 @@ This repository provides the following components of the Cylc system.
 
 ## Installation
 
-> **Warning:**
->
-> These instructions are not valid for the current beta release,
-> see the developer notes for install instructions.
+[![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)
@@ -61,14 +64,24 @@ $ 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)).
 
-### Single-User
+### For Single-User Setups
 
 Run as a standalone server using a URL token for authentication:
 
@@ -80,24 +93,26 @@ cylc gui
 $ 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.
+> 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.
 
-### Muti-User
+### For Multi-User Setups
 
-Run behind [JupyterHub](https://github.com/jupyterhub/jupyterhub).
+Run a central [JupyterHub](https://github.com/jupyterhub/jupyterhub) server
+under a user account with the privilages required to spawn `cylc` processes as
+other users.
 
 ```bash
 # launch the Cylc Hub
 # (the default URL is http://localhost:8000)
 cylc hub
 ```
 
-Authentication is handled by JupyterHub which enables per-user authorisation
-(awaiting implementation).
+> Users then authenticate with the hub which launches and manages their UI
+> Server.
 
 
 ## Configuring
@@ -150,9 +165,9 @@ using the `UIServer` namespace.
 
 Currently the UI Server accepts these configurations:
 
-* `c.UIServer.ui_build_dir`
-* `c.UIServer.ui_version`
-* `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.
 
@@ -172,11 +187,21 @@ around a network and might not persist.
 
 ## 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]
@@ -187,14 +212,14 @@ around a network and might not persist.
    > 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 follow the developer instructions for the
+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
@@ -207,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/).