.. highlight:: shell

.. _README:

====
Xbus
====

.. image:: https://drone.xcg.io/api/badges/orus-io/xbus/status.svg
   :target: https://drone.xcg.io/orus-io/xbus
   :alt: Build Status

.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://bitbucket.org/orus-io/xbus/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.11 and if needed point GOROOT to
its actual root:

.. code-block:: bash

   wget https://dl.google.com/go/go1.11.13.linux-amd64.tar.gz
   tar xf go1.11.13.linux-amd64.tar.gz

   export GOROOT=`pwd`/go
   export PATH=$GOROOT/bin:$PATH


Extract the xbus sources in a fresh gopath, and build:

.. code-block:: bash

   export GOPATH=`pwd`/gopath
   export PATH=$GOPATH/bin:$PATH

   mkdir -p $GOPATH/src/bitbucket.org/orus-io/xbus

   tar x -C $GOPATH/src/bitbucket.org/orus-io/xbus -f xbus-3.0.*.tar*

   cd $GOPATH/src/bitbucket.org/orus-io/xbus

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


Running
=======

3 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>`: Administration of actors (programs that
  can connect to Xbus).

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.