Home

Awesome

Anaconda-Server Badge Anaconda-Server Badge PyPI forum Test codecov

Cylc UI Server

This project contains the Cylc UI Server which serves the Cylc UI and communicates with running Cylc Schedulers. It also bundles the GUI.

Cylc Website | Contributing | Developing | Forum

Introduction

The functionality in this repository is required to run the Cylc web user interface.

This repository provides the following components of the Cylc system.

Installation

Anaconda-Server Badge PyPI Conda-Platforms

For more information on the Cylc components and full-stack Cylc installations see the Cylc documentation.

For Single-User Setups

Install:

Conda/Mamba (preferred)Pip
conda install cylc-uiserver-basepip install cylc-uiserver

Then start your server:

cylc gui

For Multi-User Setups

Install:

Conda/Mamba (preferred)Pip + Npm
conda install cylc-uiserverpip install cylc-uiserver[hub]
npm install configurable-http-proxy

Then start your hub:

cylc hub

List Of Packages

There are a few different packages to suit different needs.

ToolPackageDescriptionCylc UI ServerJupyter HubConfigurable HTTP Proxy
pipcylc-uiserverSingle user:heavy_check_mark::x::x:
condacylc-uiserver-baseSingle user:heavy_check_mark::x::x:
condacylc-uiserver-hub-baseMulti user (without proxy):heavy_check_mark::heavy_check_mark::x:
pipcylc-uiserver[hub]Multi user (without proxy):heavy_check_mark::heavy_check_mark::x:
condacylc-uiserverMulti user:heavy_check_mark::heavy_check_mark::heavy_check_mark:

The Configurable HTTP Proxy package (Node JS) provides the reverse proxy that Jupyter Hub requires to collate user's servers behind a single URL. It can be installed via conda install configurable-http-proxy but is not available via pip (because it requires Node JS)

Other proxies including the Traefik Proxy (Python) can also fulfil this purpose, see list of Jupyter Hub proxies.

Installing Jupyter Hub Separately

The easiest way to get going with Cylc and Jupyter Hub is to install and deploy them together and launch Jupyter Hub via the cylc hub command.

conda install cylc-uiserver
cylc hub

However, you can also deploy Jupyter Hub separately from the servers it deploys (e.g. Jupyter Lab or Cylc UI Server) and launch it via the jupyterhub command.

If you are deploying Jupyter Hub separately from Cylc UI Server, these configurations may be relevant:

Running

The Cylc UIServer is a Jupyter Server extension (like JupyterLab).

For Single-User Setups

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

Note 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 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.

Configuring

Hub

The Cylc Hub will load the following files in order:

  1. System Config

    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/uiserver/jupyter_config.py)

  3. User Config

    This file

    (~/.cylc/uiserver/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.

UI Server

See the Cylc documentation for all Cylc-specific configuration options.

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.

By default the Cylc part of the UI Server log is written to ~/.cylc/uiserver/uiserver.log.

<!-- TODO: Link to Jupyter Server logging_config docs when published -->

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

Contributors Commit activity Last commit

Contributions welcome:

  1. 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.

  2. 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/uiserver/jupyter_config.py
    import os
    c.CylcUIServer.ui_build_dir = os.path.expanduser('~/cylc-ui/dist')
    

Note about testing: unlike cylc-flow, cylc-uiserver uses the pytest-tornasync plugin instead of pytest-asyncio. This means you should not decorate async test functions with @pytest.mark.asyncio.

Copyright and Terms of Use

Copyright (C) 2019-<span actions:bind='current-year'>2024</span> 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.