Xbus deployment

This section provides information on how to deploy Xbus. It is aimed at sys admins.

Components

PostgreSQL

Xbus uses a PostgreSQL database to serialize configuration and events. Deployment of a PostgreSQL server is out of the scope of this documentation; but a default setup will lead to the 5432 port being open.

Xbus server

To run an Xbus server:

xbusd serve

Add --help to see available settings.

By default, Xbus listens on the 4222 port (may be changed with the --nats-port setting).

Note the database.dsn setting that allows configuring the PostgreSQL server and database to connect to.

Building the binary: Xbus requires Go 1.13; check the README section of this documentation for details on how to build Xbus.

Xbus connectors

Programs that connect to Xbus (emitters / workers / consumers) connect to the Xbus server on the port mentioned above. These connectors do not need to expose any port.

Administration

xbusctl

Xbus is to be administered via the xbusctl program; see the xbusctl section of this documentation for details.

Docker

Images

Docker images are provided by Cloudcrane.io for the xbus binaries. All images contains a single static binaries, except for ‘xbus-fullenv’ which is based on busybox and contains all the xbus binaries.

All the images have a “/etc/xbus” volume, in which the configuration files should be mounted.

The “xbusd” image also The default volume is “/etc/xbus”. and “/var/xbus”

Depending on your support level (see `https://cloudcrane.io/nos_offres/`_), you can use one of the following set of images:

Public images

The public docker images are suitable for testing or personal use, and can be pulled from either the orus registry or the docker hub registry.

Orus registry

docker pull docker.orus.io/xbus-personal/xbusd:3.3
docker pull docker.orus.io/xbus-personal/xbusctl:3.3
docker pull docker.orus.io/xbus-personal/xbus-client:3.3
docker pull docker.orus.io/xbus-personal/xbus-http:3.3
docker pull docker.orus.io/xbus-personal/xbus-fullenv:3.3

Docker hub

docker pull orus/xbusd:3.3
docker pull orus/xbusctl:3.3
docker pull orus/xbus-client:3.3
docker pull orus/xbus-http:3.3
docker pull orus/xbus-fullenv:3.3

“Enterprise” images

You can use the “enterprise” images if you subscribed to the “standard” support contract. If you don’t have a login to pull the images, please get in touch with us.

docker pull docker.orus.io/xbus-enterprise/xbusd:3.3-enterprise
docker pull docker.orus.io/xbus-enterprise/xbusctl:3.3-enterprise
docker pull docker.orus.io/xbus-enterprise/xbus-client:3.3-enterprise
docker pull docker.orus.io/xbus-enterprise/xbus-http:3.3-enterprise
docker pull docker.orus.io/xbus-enterprise/xbus-fullenv:3.3-enterprise

“LTS” images

You can use the “LTS” images if you subscribed to the “premium” support contract. If you don’t have a login to pull the images, please get in touch with us.

docker pull docker.orus.io/xbus-lts/xbusd:3.3-lts
docker pull docker.orus.io/xbus-lts/xbusctl:3.3-lts
docker pull docker.orus.io/xbus-lts/xbus-client:3.3-lts
docker pull docker.orus.io/xbus-lts/xbus-http:3.3-lts
docker pull docker.orus.io/xbus-lts/xbus-fullenv:3.3-lts

Create xbusd.yaml config file

Use the following sample to create a configuration file called xbusd.yaml:

Assuming that the configuration file xbusd.yaml is in the /var/data/xbus/etc directory:

Set the database host reachable from the docker, db name, db user and db password.

Add option to disable database ssl mode.

Set the nats host and port.

/var/xbus is the default WORKDIR of the xbusd image, so create a directory certs in /var/data/xbus/var directory.

Init xbus db

Run xbusd init command from the docker to initialize the database:

docker run --rm \
  -v /var/data/xbus/etc:/etc/xbus -v /var/data/xbus/var:/var/xbus \
  xbusd init

Generate xbus certificates

Generate keys:

docker run --rm \
    -v /var/data/xbus/etc:/etc/xbus -v /var/data/xbus/var:/var/xbus \
    xbusd key generate

Generate certificates:

The –host-defs option is a comma separated list that defines the hosts for which the server-ca is generated. It can be a host names, IPs or a domain names.

docker run --rm \
    -v /var/data/xbus/etc:/etc/xbus -v /var/data/xbus/var:/var/xbus \
    xbusd cert generate server-ca --host-defs <HOST DEFS>

docker run --rm \
    -v /var/data/xbus/etc:/etc/xbus -v /var/data/xbus/var:/var/xbus \
    xbusd cert generate client-ca

Start xbusd

Run xbusd serve:

docker run --rm -d --restart always -t -p 4222:4222 --name xbusd \
    -v /var/data/xbus/etc:/etc/xbus -v /var/data/xbus/var:/var/xbus \
    xbusd serve

Register xbusctl

Use the following sample to create a configuration file called xbusctl.yaml

Assuming that the configuration file xbusctl.yaml is in the /var/data/xbus/etc directory and its account-name is ctl:

Generate keys:

docker run --rm -v /var/data/xbus/etc:/etc/xbus xbusctl key generate

Register:

docker run --rm -v /var/data/xbus/etc:/etc/xbus xbusctl register

Accept account:

docker exec -ti xbus xbusd -v /var/data/xbus/etc:/etc/xbus account accept "ctl"

Register again:

docker run --rm -v /var/data/xbus/etc:/etc/xbus xbusctl register

Stop xbusd

docker stop xbusd