Quickstart
==========

Preresquisite
-------------

We assume that xbus binaries are already installed in your path. If not, you
can download them from `xbus download page`_.

.. _xbus download page: https://bitbucket.org/orus-io/xbus/downloads/

Setup a server
--------------

Write a configuration file (possibly in /etc/xbus/xbusd.yaml):

.. code-block:: bash

    mkdir -p ~/.config/xbus
    cat > ~/.config/xbus/xbusd.yaml <<EOF
    database:
      dsn: dbname=xbus user=xbus password=xbus
    EOF

From the CWD in which the server will run, initialize the certdir
(future version will not need this step):

.. code-block:: bash

    mkdir -p certs/xbusd

Initialize the database:

.. code-block:: bash

    xbusd init

Initialize the keys and certs:

.. code-block:: bash

    xbusd key generate
    xbusd cert generate server-ca --host-defs localhost
    xbusd cert generate client-ca

Run it:

.. code-block:: bash

    xbusd serve

Setup a ctl client
------------------

Setup the conf && generate a key:

.. code-block:: bash

    echo "account-name: admin" > ~/.config/xbus/xbusctl.yaml
    xbusctl key generate

You can check the result in `~/.config/xbus/admin.certs`.

Registration 1st step:

.. code-block:: bash

    xbusctl register

2nd step is to accept the account on the server, with xbusd (because it is the first account, next accounts should be accepted with xbusctl):

.. code-block:: bash

    xbusd account accept myname

3rd and last step, let xbusctl know it has been accepted:

.. code-block:: bash

    xbusctl register

Setup a client
--------------

Write a basic configuration file to initialize a new account with 1 emitter, 1
consumer and 1 worker (you can add/remove as many actors you want), and save it
as "xbus-client.yaml":

.. code-block:: yaml

    account-name: demo-client
    nats-url: nats://localhost:4222/
    actors:
      emitter-1:
        kind: emitter
        roles: [helloworld]
        service:
          type: demo.helloworld
          settings:
            interval: 4
            message: "Hello world"
      consumer-1:
        kind: consumer
        roles: [print]
        service:
          type: demo.print-to-console
      worder-1:
        kind: worker
        roles: [relay]
        service:
          type: demo.relay
          settings:
            processing-duration: 6

Do the 1st registration step, by running xbus-client:

.. code-block:: bash

    xbus-client --config xbus-client.yaml register

If no error occur, the account and actors are now created in a pending state
on the server, and the `xbus-client.yaml` file was updated with their new ID,
among other things.

The 2nd registration step is to accept the account an actors on the server
side. It should be done with :program:`xbusctl account accept` and
:program:`xbusctl actor accept`:

.. code-block:: bash

    xbusctl account accept demo-client
    xbusctl actor accept emitter-1
    xbusctl actor accept consumer-1
    xbusctl actor accept worker-1

The 3rd and last step is to let your client know that it was accepted by
re-running the 'register' command:

.. code-block:: bash

    xbus-client --config xbus-client.yaml register

From this point, any connection from the client will be authenticated by a
TLS certificate.

You can add more actors at any time and redo the registration steps, only
the new actors will be impacted (not the account or the older actors).

Make sure the client is able to start the services:

.. code-block:: bash

    xbus-client serve

You should have some error logs like the following ones (because no pipeline has
been configured yet):

.. code-block:: bash

    [23989] [ERR] Error sending envelope: No matching pipeline
    [23989] [ERR] send failed: No matching pipeline

You can hit CTRL-C to stop the client, you can also let it run until the pipeline
is activated and see what happens.

Setup a pipeline
----------------

Write a pipeline file ``demo.yaml``:

.. code-block:: yaml


    nodes:
    - id: relay
      type: worker
      actors:
      - worker-1
      inputs:
      - default
      outputs:
      - default
    - id: sink
      type: consumer
      roles:
      - print
      rolebroadcast: true
      inputs:
      - default
    - id: source
      type: emitter
      sourcematch:
        eventtypes:
        - demo.simplemessage
      outputs:
      - default
    edges:
    - source.default->relay.default
    - relay.default->sink.default

Load an activate the pipeline in the bus:

.. code-block:: bash

    xbusctl pipeline save demo 1.0 demo.yaml
    xbusctl pipeline status demo 1.0 --active


Go live
-------

Now starts the client, which will run all the actors in a single process:

.. code-block:: bash

    xbus-client serve

You should see the various actors logging their actions.