.. _web-ui:

Running the OpenQuake engine through the Web UI
===============================================

The OpenQuake engine server provides an `HTTP RESTful API <https://en.wikipedia.org/wiki/Representational_state_transfer>`_ 
and a web GUI, the WebUI. It's built on top of `Django <https://www.djangoproject.com/>`_, 
`jQuery <https://jquery.com/>`_ and `BACKBONE.js <http://backbonejs.org/>`_.

The OpenQuake engine server is used to submit new jobs, watch calculation progress, retrieve results and more.

The :ref:`API document <rest-api>` provides the full list of available endpoints. Several authentication mechanisms are supported and can 
be enabled with a :ref:`custom configuration <server>`.

The OpenQuake engine WebUI does not require any special software on the client side except for a browser. Supported 
browsers are:

- Mozilla Firefox >= 38
- Google Chrome
- Microsoft Internet Explorer >= 10
- Microsoft Edge
- Apple Safari >= 6

Starting the OpenQuake engine server
------------------------------------

*******
Windows
*******

Double click on the "OpenQuake engine (webui)" icon located on the desktop, or use the link in the 'Start' menu.

***********************************************
Linux and macOS from installers or from sources
***********************************************

In a terminal type::

	$ oq webui start

*******************
Linux from packages
*******************

A ``systemd`` service will take care of the OpenQuake engine server, starting it at boot. Please refer to 
:ref:`Configure the systemd services page <rhel>`.

Using the OpenQuake engine WebUI
--------------------------------

Open the browser and load the http://localhost:8800/engine page

.. image:: _images/webui/webui-main.gif

*******************
Start a calculation
*******************

Before starting a new calculation you need to prepare inputs. All the inputs file and the ``job.ini`` must be placed in 
a compressed zip file.

To start a calculation, having the input zip file, select the ``Run a Calculation`` button in the header menu. A dialog 
window will appear: select the zip file to be uploaded and press ``Open`` to confirm.

.. image:: _images/webui/webui-run.gif

Each running calculation can be stopped with the ``Abort`` button; this will interrupt the calculation immediately and 
revoke any pending task for that specific job. Note: only a calculation started from the WebUI can be stopped via the 
``Abort`` button; to stop a calculation started by the command line interface the ``oq abort`` command must be used instead.

*********************
Watch the console log
*********************

It is possible to watch the log from a running calculation

.. image:: _images/webui/webui-log.gif

The log from a previous run can be also inspected.

****************
Download outputs
****************

If a calculation has run successfully an ``Outputs`` button is provided. Click the ``Outputs`` button to see the list of 
outputs available for the specific calculation type. Output availability depends on the type of artifacts generated by 
the calculation. The possible formats are ``xml``, ``csv``, ``npz``, ``zip``. Click on the desired output/format to 
download the corresponding file.

.. image:: _images/webui/webui-outputs.gif

*********************************************************************************
Run a postprocessing (or risk) calculation on top of a previously computed hazard
*********************************************************************************

To run a postprocessing or risk calculation on top of a previous hazard one you have to click the ``Continue`` button on 
the corresponding hazard calculation and select the zip file containing the ``job.ini`` and the related inputs.

.. image:: _images/webui/webui-risk.gif

********************
Remove a calculation
********************

To hide a calculation from the list press the ``Remove`` button.

.. image:: _images/webui/webui-remove.gif

The calculation is removed from the calculations list, but it is not actually removed from the database nor from the 
datastore.

******************
Calculation status
******************

A calculation can be in one of the following statuses: ``created``, ``executing``, ``complete``, ``failed``.

.. image:: _images/webui/webui-status.gif

The reason behind a failed calculation can be inspected by using the ``Traceback`` button.