.. _http-setup: 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: .. code-block:: yaml 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: .. code-block:: bash 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: .. code-block:: bash xbus-http [ --config path/to/xbus-http.yaml ] serve Installation is over, the API should be usable right away. .. _http-setup-accounts: 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 :ref:`http-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: .. code-block:: yaml 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: .. code-block:: bash 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: .. code-block:: bash 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