.. highlight:: shell

.. _README:

====
Xbus
====

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://orus.io/xbus/xbus/raw/branch/default/LICENSE
    :alt: License

Xbus provides high-level application messaging on top of `NATS`_.


Requirements
============

Golang
------

This is a `Go`_ project. We build and test xbus with go 1.13.x

Postgresql
----------

Xbus uses a `postgresql`_ database 9.5+ to serialize configuration and events.

Build
=====

Build as a regular `Go`_ package::

    make devtools
    make install

Build from the source package
-----------------------------

Make sure the 'go' found in the PATH is go 1.13 and its GOROOT/GOPATH are
properly test.

Extract the xbus sources, and build:

.. code-block:: bash

   tar xf xbus-3.1.*.tar*

   cd xbus-3.1*

   make install

   # optionally run the tests:
   # make test POSTGRES_DSN="dbname=xbus-tests user=xbus password=xbus sslmode=disable"
   make doc dist


Running
=======

5 binaries are created:

- :ref:`xbusd <xbusd>`: Main Xbus program.

- :ref:`xbusctl <xbusctl>`: Xbus administration program (ctl = "control");
  remotely connects to :ref:`xbusd <xbusd>`.

- :ref:`xbus-client <xbus-client>`: Default xbus client. Provides demo actors
  and tooling to administration a client account.

- :ref:`xbus-http <xbus-http>`: The Xbus HTTP gateway.

- :ref:`xbus-fullenv <xbus-fullenv>`: A dev/test utility that build complete
  xbus path from a single yaml file.

Each program may be run with ``--help`` to see available commands / flags / etc.

Warning: `xbusd <xbusd>` can produce a LOT of logs when placed under load.

The server will crash if it is unable to write to stdio/stderr.
Init systems that implement rate limitation for logs (such as `systemd`) may
cause `xbusd <xbus>` to crash if the server exceeds this limit.

Updating
========

- The ``migration`` directory contains scripts one can use to migrate Xbus
  databases from one version to the other.

- The ``migration`` directory contains scripts one can use to migrate Xbus
  databases from one version to the other.

- Run ``xbusd migrate`` to migrate Xbus databases from one version to the other.

.. _Go: https://golang.org/
.. _NATS: https://nats.io/
.. _postgresql: https://www.postgresql.org/