Cylc UI Server

This project contains the Cylc UI Server. A JupyterHub-compatible application, used to serve the Cylc UI, and to communicate with running Cylc Schedulers.

Cylc Website | Contributing | Developing

Contents

• Installation
• Introduction
• Copyright

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.

• The UI

  This is the Cylc web app that provides control and monitoring functionalities for Cylc workflows.

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

• The Hub

  This launches UI Servers, provides a proxy for running server and handles authentication. It is a JupyterHub server.

Installation

For production:

# via conda (preferred)
$ conda install cylc-uiserver

# via pip
$ pip install cylc-uiserver

Running

$ cylc hub

The default URL is http://localhost:8000.

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/config_defaults.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/config.py)

3. User Config

   This file

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

See the Jupyterhub documentation for details on configuration options.

UI Server

The UI Server is (currently) also configured from the same configuration file(s) as the hub using the UIServer namespace.

Currently the UI Server accepts these configurations:

• c.UIServer.ui_build_dir
• c.UIServer.ui_version
• c.UIServer.logging_config
• c.UIServer.scan_iterval

See the cylc.uiserver.main.UIServer file for details.

Developing

1. Read the Contributing page.

2. Fork and clone this repo.

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

4. For UI development set the following configuration to use your UI build (rather than the default bundled UI build):

   # ~/.cylc/hub/config.py
   c.UIServer.ui_build_dir = '~/cylc-ui/dist'  # path to build

Copyright and Terms of Use

Copyright (C) 2019-2021 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.