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