Quickstart

Setup a server

Write a configuration file (possibly in /etc/xbus/xbusd.yaml):

mkdir -p ~/.config/xbus
echo "database: dbname=xbus user=xbus password=xbus" > ~/.config/xbus/xbusd.yaml

From the CWD in which the server will run, initialize the certdir (future version will not need this step):

mkdir -p certs/xbusd

Initialize the database:

xbusd init

Initialize the keys and certs:

xbusd key generate
xbusd cert generate server-ca
xbusd cert generate client-ca

Run it:

xbusd serve

Setup a ctl client

Setup the conf && generate a key:

xbusctl --account-name myname key generate

You can check the result in ~/.config/xbus/xbusctl.yaml.

Registration 1st step:

xbusctl register

2nd step is to accept the account on the server, with xbusd (because it is the first account, next accounts should be accepted with xbusctl):

xbusd account list
# identify the account and copy its csr fingerprint, then:
xbusd account accept "<paste fingerprint>"

3rd and last step, let xbusctl know it has been accepted:

xbusctl register

Setup a client

Write a basic configuration file to initialize a new account with 1 emitter, 1 consumer and 1 worker (you can add/remove as many actors you want), and save it as “xbus-client.yaml”:

account-name: demo-client
nats-url: nats://localhost:4222/
actors:
  "0":
    name: "emitter-1"
    kind: emitter
    roles: [helloworld]
    service:
      type: demo.helloworld
      settings:
        interval: 4
        message: "Hello world"
  "1":
    name: "consumer-1"
    kind: consumer
    roles: [print]
    service:
      type: demo.print-to-console
  "2":
    name: "worker-1"
    kind: worker
    roles: [relay]
    service:
      type: demo.relay
      settings:
        processing-duration: 6

Do the 1st registration step, by running xbus-client:

xbus-client --config xbus-client.yaml register

If no error occur, the account and actors are now created in a pending state on the server, and the xbus-client.yaml file was updated with their new ID, among other things.

The 2nd registration step is to accept the account an actors on the server side. It should be done with xbusctl account accept and xbusctl actor accept.

The 3rd and last step is to let your client know that it was accepted by re-running the ‘register’ command:

xbus-client --config xbus-client.yaml register

From this point, any connection from the client will be authenticated by a TLS certificate.

You can add more actors at any time and redo the registration steps, only the new actors will be impacted (not the account or the older actors).

Make sure the client is able to start the services:

xbus-client serve

Setup a graph

Write a graph file demo.yaml:

name: demo
version: "0.1"
status: active
nodes:
- id: relay
  type: worker
  actors:
  - worker-1
  inputs:
  - default
  outputs:
  - default
- id: sink
  type: consumer
  roles:
  - print
  rolebroadcast: true
  inputs:
  - default
- id: source
  type: emitter
  sourcematch:
    eventtypes:
    - demo.simplemessage
  outputs:
  - default
edges:
- source.default->relay.default
- relay.default->sink.default

Load an activate the graph in the bus:

xbusctl graph push demo.yaml

The graph file will be updated with a unique ID, unless some error occured.

Go live

Now starts the client, which will run all the actors in a single process:

xbus-client serve

You should see the various actors logging their actions.