.. _xbus-fullenv:

Xbus Fullenv
============

:program:`xbus-fullenv` is a command line tool that can setup xbusd, xbusctl
and xbus-client(s) in a single operation, based on single configuration file.

It is aimed at setting up development and tests environments without going
through all the steps manually, making it easy to reproduce a given setup.

:program:`xbus-fullenv`
-----------------------

.. program:: xbus-fullenv

Usage
~~~~~

    ``xbus-fullenv <command> [ --target dir ] [ --dsn dsn ] configurationfile``

Options
~~~~~~~

.. option:: configurationfile

    A yaml file path. The file content is
    :ref:`documented below <xbus-fullenv-configfile>`.

.. option:: --dsn dsn

    Set the database dsn. Will override the dsn present in the configuration
    file.

.. option:: --target dir

    Target directory path. If omitted, a directory is created in the TEMPDIR.

.. option:: --debug

    Enable debug mode

.. option:: --trace

    Enable trace mode

.. option:: --no-prompt

    In interactive mode, disable the '>' prompt. Useful for controling the
    fullenv from another program.

.. envvar:: XBUS_TEST_POSTGRES_DSN

    Default database dsn if not already set in the configuration file or by the
    :option:`--dsn` option.

Commands
~~~~~~~~

setup
'''''

Setup the server and clients in the target directory.

Usage:

.. autocmd:: xbus-fullenv setup

run
'''

Setup the server and clients in the target directory, then opens an interactive
mini-shell.

The available commands are:

client-config <name>
    returns the configuration path of a client

wd
    returns the environment work directory

startup
    start the clients

shutdown
    shutdown the clients

quit
    shutdown everything and quit

help, ?

    Inline help

Usage:

.. autocmd:: xbus-fullenv run


.. _xbus-fullenv-configfile:

Configuration file
------------------

The configuration file is a yaml file composed of 3 top-level keys:

xbusd
~~~~~

A xbusd configuration file content, that can be empty.
If the database settings are not given, they are copied from either the
command line flag :option:`--dsn`, or the environment variable
:envvar:`XBUS_TEST_POSTGRES_DSN`.

Example:

.. code-block:: yaml

    xbusd:
      database:
        dsn: dbname=xbus user=xbus password=xbus sslmode=disable


clients
~~~~~~~

A list of xbus-client configurations. These clients will be automatically
registered along with their actors.

Extra attributes can be added to each client settings:

autostart
    If set to false, the client will not be started by the 'startup' command.

custom-xbus-client
    If set, the program will be used instead of 'xbus-client serve' to start
    the client.

Example:

.. code-block:: yaml

    clients:
      - account-name: test-emitter
        autostart: false
        actors:
          "0":
            name: test-emitter
            kind: emitter
            status: enabled
            roles: [tester]
      - account-name: test-consumer
        autostart: true
        actors:
          "0":
            name: test-consumer
            kind: consumer
            status: enabled
            roles: [tester]
            service:
              type: demo.print-to-console


pipelines
~~~~~~~~~

A dictionary of pipeline definitions.

The key format is the following:

    ``<name>[-<version>][#<status>]``

Where ``<status>`` can be ``draft``, ``active`` or ``inactive``.

Example:

.. code-block:: yaml

    pipelines:
      defaultpipeline-v1#active:
        nodes:
        - id: source
          type: emitter
          roles: [tester]
          rolebroadcast: true
          sourcematch:
            eventtypes:
            - demo.msg
          outputs:
          - default
        - id: sink
          type: consumer
          roles:
          - tester
          rolebroadcast: true
          inputs:
          - default
        edges:
        - source -> sink