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.