Package: cylc-uiserver
Cylc UI ServerThis 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|ForumIntroductionThe functionality in this repository is required to run the Cylc web user
interface.This repository provides the following components of the Cylc system.The UIThis is the Cylc web app that provides control and monitoring functionalities
for Cylc workflows.NoteThe UI is developed in a separate repositoryhttps://github.com/cylc/cylc-uiThe UI ServerThis 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 aJupyter Server.The HubIn multi-user setups this launches UI Servers, provides a proxy for running
server and handles authentication. It is aJupyterHubserver.InstallationFor more information on the Cylc components and full-stack Cylc installations
see theCylc documentation.For Single-User SetupsVia conda (preferred):condainstallcylc-uiserverVia pip:pipinstallcylc-uiserverFor Multi-User SetupsVia conda (preferred):condainstallcylc-uiserver-hubVia pip (consult jupyterhub documentation):pipinstallcylc-uiserver[hub]RunningThe Cylc UIServer is aJupyter Serverextension (likeJupyterLab).For Single-User SetupsRun as a standalone server using a URL token for authentication:# launch the Cylc GUI and open a browser tab$cylcgui# alternatively the same app can be opened with the jupyter command$jupytercylcNoteBy 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 SetupsRun a centralJupyterHubserver
under a user account with the privileges required to spawncylcprocesses as
other users.# launch the Cylc Hub# (the default URL is http://localhost:8000)$cylchubUsers then authenticate with the hub which launches and manages their UI Server.ConfiguringHubThe Cylc Hub will load the following files in order:System ConfigThese are the Cylc defaults which are hardcoded within the repository.(<python-installation>/cylc/uiserver/jupyter_config.py)Site ConfigThis file configures the Hub/UIS for all users. The default path can be
changed by theCYLC_SITE_CONF_PATHenvironment variable.(/etc/cylc/uiserver/jupyter_config.py)User ConfigThis file(~/.cylc/uiserver/jupyter_config.py)Alternatively a single config file can be provided on the command line.cylchub--configWarningIf specifying a config file on the command line, the system config containing
the hardcoded Cylc default willnotbe loaded.NoteThe hub can also be run using thejupyterhubcommand, however, you
must source the configuration files manually on the command line.See the JupyterHub documentation for details on configuration options.UI ServerSee theCylc documentationfor all Cylc-specific configuration options.The Cylc UI Server is aJupyter Serverextension.
Jupyter Server can run multiple extensions. To control the extensions that
are run use theServerApp.jpserver_extensionsconfiguration, see theJupyter Server configuration documentation.By default the Cylc part of the UI Server log is written to~/.cylc/uiserver/uiserver.log.UIThe 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.DevelopingContributions welcome:Read thecontributingpage.Development setup instructions are in thedeveloper docs.Involved change proposals can be found in theadmin pages.Touch base in thedevelopers chat.Install from source into your Python environment:pipinstall-e.[all]NoteIf you want to run with a development copy of Cylc Flow you must install
it first elsepipwill download the latest version from PyPi.For UI development follow the developer instructions for thecylc-uiproject, then
set the following configuration so Cylc uses your UI build
(rather than the default bundled UI build):# ~/.cylc/uiserver/jupyter_config.pyimportosc.CylcUIServer.ui_build_dir=os.path.expanduser('~/cylc-ui/dist')Note about testing: unlike cylc-flow, cylc-uiserver uses thepytest-tornasyncplugin
instead ofpytest-asyncio.
This means you should not decorate async test functions with@pytest.mark.asyncio.Copyright and Terms of UseCopyright (C) 2019-2023NIWA & 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, seeGNU licenses.