.. _user/workbench:

#########
Workbench
#########

Connectware ships with a running Node-RED (https://nodered.org) application.

To start working with the prototyping Node-RED Workbench, on the navigation
panel click ``Services`` and on the sidebar, click ``Node Red Workbench``. This will open the running Node-RED 
editor for the Workbench in another browser tab.

  .. figure:: ../resources/workbench/menu_item_workbench.png
     :width: 200px

.. note::

  However, this Node-RED workbench is not intended to be used in
  production-ready services but rather for quick and easy prototyping tests. In
  deployments where Node-RED should be used in production, the recommended setup
  is to create a service commissioning file which installs a Node-RED container
  as :ref:`Cybus::Container resource
  <user/services/structure/resources/container>` on its own. This way, the
  authors of the service have the full control over the versioning and life
  cycle of the Node-RED instance.

Further instructions on how to work with Node-RED can be found here:
https://nodered.org/docs

For connecting the Node-RED flow to the Connectware API, Connectware
can be reached by using the server name ``connectware`` both for MQTT (1883) and
HTTPS (443) connections.

  .. figure:: ../resources/workbench/nodered-mqtt-server.png
     :width: 750px

Additionally, when subscribing or publishing to the Connectware server, a
suitable ``username`` and ``password`` has to be set manually in the Node-RED
workbench. You need to ensure that the given user has sufficient permissions (or
suitable roles) in order to access the topics in question. See also
:ref:`user/user_management`.

  .. figure:: ../resources/workbench/nodered-username.png
     :width: 750px

Flows in Git Repositories
=========================

The Workbench allows to store Flows in any external Git Repository. This is
called the "Workbench Projects" feature.

You can get familiar with Node-RED's Projects feature
(https://nodered.org/docs/user-guide/projects/) to understand how this works in
practice. In order to enable it in your Connectware, you must modify the
configuration as described next.

Configuration
-------------

In order to enable the `workbench projects` feature, the following
:ref:`user/configuration/env` must be configured:

- **CYBUS_WORKBENCH_PROJECTS_ENABLED:** If `true`, the Projects feature will be
  enabled. Default: `false`.

If the feature should be enabled, this value needs to be set to `true` in the
environment variable configuration. By default the settings should look like
this:

.. code-block:: bash

  # Workbench Configuration
  CYBUS_WORKBENCH_PROJECTS_ENABLED=false