Xbus HTTP - Installation

The 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).

Theoraticaly several 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!).

Installing xbus-http

Setting up a xbus-http instance is like setting up a xbusctl.

First, write a configuration file. By default, xbus-http will look for a xbus-http.yaml file in ~/.config/xbus, then /etc/xbus. You can also force a configuration file path with the --config flag.

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.

Configuring accounts

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]

Use 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