=============== 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 :ref:`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 :ref:`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 ~~~~~~~~~~~~~ .. parsed-literal:: docker pull docker.orus.io/xbus-personal/xbusd:|version| docker pull docker.orus.io/xbus-personal/xbusctl:|version| docker pull docker.orus.io/xbus-personal/xbus-client:|version| docker pull docker.orus.io/xbus-personal/xbus-http:|version| docker pull docker.orus.io/xbus-personal/xbus-fullenv:|version| Docker hub ~~~~~~~~~~ .. parsed-literal:: docker pull orus/xbusd:|version| docker pull orus/xbusctl:|version| docker pull orus/xbus-client:|version| docker pull orus/xbus-http:|version| docker pull orus/xbus-fullenv:|version| "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. .. parsed-literal:: docker pull docker.orus.io/xbus-enterprise/xbusd:|version|-enterprise docker pull docker.orus.io/xbus-enterprise/xbusctl:|version|-enterprise docker pull docker.orus.io/xbus-enterprise/xbus-client:|version|-enterprise docker pull docker.orus.io/xbus-enterprise/xbus-http:|version|-enterprise docker pull docker.orus.io/xbus-enterprise/xbus-fullenv:|version|-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. .. parsed-literal:: docker pull docker.orus.io/xbus-lts/xbusd:|version|-lts docker pull docker.orus.io/xbus-lts/xbusctl:|version|-lts docker pull docker.orus.io/xbus-lts/xbus-client:|version|-lts docker pull docker.orus.io/xbus-lts/xbus-http:|version|-lts docker pull docker.orus.io/xbus-lts/xbus-fullenv:|version|-lts Create xbusd.yaml config file ----------------------------- Use the following sample to create a configuration file called xbusd.yaml: .. literalinclude:: ../etc/xbusd_sample.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 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`` .. literalinclude:: ../etc/xbusd_sample.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 .. _Go: https://golang.org/ .. _PostgreSQL: https://www.postgresql.org/