Quickstart

Preresquisite

We assume that xbus binaries are already installed in your path. If not, you can download them from xbus download page.

Setup a server

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

mkdir -p ~/.config/xbus
cat > ~/.config/xbus/xbusd.yaml <<EOF
database:
  dsn: dbname=xbus host=/var/run/postgresql
EOF

Initialize the certdir next to the configuration file:

mkdir -p ~/.config/xbus/certs/xbusd

Initialize the database:

xbusd init

Initialize the keys and certs:

xbusd key generate
xbusd cert generate server-ca --host-defs localhost
xbusd cert generate client-ca

Run it:

xbusd serve

Setup a ctl client

Setup the conf && generate a key:

echo "account-name: admin" > ~/.config/xbus/xbusctl.yaml
xbusctl key generate

You can check the result in ~/.config/xbus/admin.certs.

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 accept admin

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:
  emitter-1:
    kind: emitter
    roles: [helloworld]
    service:
      type: demo.helloworld
      settings:
        interval: 3000
        message: "Hello world"
  consumer-1:
    kind: consumer
    roles: [print]
    service:
      type: demo.print-to-console
  worker-1:
    kind: worker
    roles: [relay]
    service:
      type: demo.relay
      settings:
        processing-duration: 5

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 a new file demo-client.certs was created with the account certificates.

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:

xbusctl account accept demo-client
xbusctl actor accept emitter-1
xbusctl actor accept consumer-1
xbusctl actor accept worker-1

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

You should have some error logs like the following ones (because no pipeline has been configured yet):

[23989] [ERR] Error sending envelope: No matching pipeline
[23989] [ERR] send failed: No matching pipeline

You can hit CTRL-C to stop the client, you can also let it run until the pipeline is activated and see what happens.

Setup a pipeline

Write a pipeline file demo.yaml:

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 pipeline in the bus:

xbusctl pipeline save demo 1.0 demo.yaml
xbusctl pipeline status demo 1.0 --active

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.