Xbus HTTP - Installation¶
xbus-http program itself needs very little configuration. All the
actor-related settings will be stored in the xbus server itself.
It listens in HTTP (not HTTPS!) on the port 8911 (not configurable yet).
xbus-http can be running at the same time, including
several instances using the same configuration file. This use-case was not
really tested though, so if you need such a setup, make sure you test it properly
(and tell us how did it go!).
Setting up a
xbus-http instance is like setting up a
First, write a configuration file. By default,
xbus-http will look for a
xbus-http.yaml file in
/etc/xbus. You can also
force a configuration file path with the
Here is a sample configuration file:
account-name: my-http-gateway # optionnaly, you can also define: nats-url: nats://localhost:4222
The registration process is done the way it is done for any other client:
xbus-http [ --config path/to/xbus-http.yaml ] register xbusctl account accept my-http-gateway xbus-http [ --config path/to/xbus-http.yaml ] register
The configuration is over, you can now start your gateway:
xbus-http [ --config path/to/xbus-http.yaml ] serve
Installation is over, the API should be usable right away.
In order to use the API, a client needs a API key. For the webhooks, only the actor needs to be properly configured on the server (see Webhooks).
In both case, the first step is to configure an account an its actors. The simpliest way to do that is to use xbus-client.
Let’s say we need to setup a http client that will use the API as an emitter and webhooks as a consumer.
Create a configuration file (say, “web-frontend.yaml”) suitable for xbus-client with such an account definition:
account-name: my-web-frontend-app actors: "0": name: "web-frontend-emitter" kind: emitter roles: [web-frontend] "1": name: "web-frontend-consumer" kind: consumer roles: [web-frontend]
xbus-client to register the account, then
xbusctl to accept the
account and the actors:
xbus-client --config web-frontend.yaml register xbusctl actor accept web-frontend-emitter xbusctl actor accept web-frontend-consumer xbusctl account accept my-web-frontend-app
No need to run a final
xbus-client register: we don’t need the certificates.
The configuration file is not needed either: it was just a way to create the
xbus account and actors.
Now that the account is ready, we can generate a API key for it so the HTTP client can set the proper HTTP header in its requests:
xbusctl account renew-apikey my-web-frontend-app # The api key can be forced with xbusctl account set-apikey my-web-frontend-app MyHardToGuessAPIKey # if you ever lose the apikey, you can get it back with: xbusctl account get-apikey my-web-frontend-app