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 | Contributing | Developing | Forum
The functionality in this repository is required to run the Cylc web user 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.
-
The Hub
In multi-user setups this launches UI Servers, provides a proxy for running server and handles authentication. It is a JupyterHub server.
For more information on the Cylc components and full-stack Cylc installations see the Cylc documentation.
# via conda (preferred)
$ conda install cylc-uiserver
# via pip
$ pip install cylc-uiserver
# via conda (preferred)
$ conda install cylc-uiserver-hub
# via pip (consult jupyterhub documentation)
$ pip install cylc-uiserver[hub]
The Cylc UIServer is a Jupyter Server extension (like JupyterLab).
Run as a standalone server using a URL token for authentication:
# 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.
Run a central JupyterHub server
under a user account with the privileges required to spawn cylc
processes as
other users.
# 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.
The Cylc Hub will load the following files in order:
-
System Config
These are the Cylc defaults which are hardcoded within the repository.
(
<python-installation>/cylc/uiserver/jupyter_config.py
) -
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
) -
User Config
This file
(
~/.cylc/hub/jupyter_config.py
)
Alternatively a single config file can be provided on the command line.
$ cylc hub --config
Warning:
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.
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
c.CylcUIServer.site_authorization
c.CylcUIServer.user_authorization
See the cylc.uiserver.app.UIServer
file for details.
The Cylc UI Server is a
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.
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.
Contributions welcome:
- Read the contributing page.
- Development setup instructions are in the developer docs.
- Involved change proposals can be found in the admin pages.
- Touch base in the developers chat.
-
Install from source into your Python environment:
$ pip install -e .[all]
Note:
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. -
For UI development follow the developer instructions for the cylc-ui project, then set the following configuration so Cylc uses your UI build (rather than the default bundled UI build):
# ~/.cylc/hub/jupyter_config.py c.CylcUIServer.ui_build_dir = '~/cylc-ui/dist' # path to build
Copyright (C) 2019-2022 NIWA & British Crown (Met Office) & Contributors.
Cylc is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, 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.