Install events-into-websocket plugin into headless wallet

Goal

This article will guide you to install the events-into-websocket plugin in Hathor headless wallet.

The events-into-websocket plugin is part of the external notification feature. To know more about this feature, see Hathor external notifications.

Requirement

Hathor headless wallet $\ge$ v0.19.0

Step-by-step

1. Install dependency.
2. Configure and enable the plugin.

Step 1: install dependency

Source code

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Run the command to install the dependency:

npm install ws@^8.11.0

Docker container

If you installed Hathor headless wallet as a Docker container, you must build a new Docker image, with all installed dependencies. The image that Hathor Labs provides at Docker Hub does not come with all dependencies installed for this plugin:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Create a new empty Dockerfile file and write in it just the following lines:

FROM hathornetwork/hathor-wallet-headless

RUN npm install ws@^8.11.0

3. Build a new Docker image, based in the Dockerfile you created in the previous substep:

docker build --file Dockerfile .

At the end of this step, you will have built a new Docker image.

Docker compose

If you installed Hathor headless wallet along Hathor full node with Docker compose, you must build a new Docker image, with all installed dependencies. The image that Hathor Labs provides at Docker Hub does not come with all installed dependencies for this plugin:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Create a new empty Dockerfile file and write in it just the following lines:

FROM hathornetwork/hathor-wallet-headless

RUN npm install ws@^8.11.0

3. Build a new Docker image, based in the Dockerfile you created in the previous substep:

docker build --file Dockerfile .

At the end of this step, you will have built a new Docker image.

Step 2: configure and enable the plugin

Source code

If you installed Hathor headless wallet from source code, you must modify both the src/config.js file and the command to start the application, to respectively enable and configure the plugin:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Open the src/config.js file.
3. Add 'ws' to the array of values of the enabled_plugins property to enable the plugin.

If you are enabling multiple plugins, value shall be an array of plugin ids: enabled_plugins: ['PluginId1', 'PluginId2', ...].

At the end of this substep, the config.js file will be as follows:

hathor-wallet-headless/src/config.js

module.exports = {

  ...

  enabled_plugins: ['ws'],

  plugin_config: {},

  ...

};

Note that the events-into-websocket plugin runs a websocket server along with Hathor headless wallet.

4. Choose the port you want the websocket clients to connect.
5. To start the wallet application, append the --plugin_ws_port <websocket_server_chosen_port> parameter, replacing the <websocket_server_chosen_port> placeholder with your chosen port.

At the end of this step, the command to start the wallet application will be as follows:

npm start -- --plugin_ws_port <websocket_server_chosen_port>

Docker container

If you installed Hathor headless wallet as a Docker container, you must add parameters to the docker run command to enable and configure the plugin, and use the new image you built in the previous step:

1. Append --enabled_plugins='ws' to the docker run command.

If you are enabling multiple plugins, parameter value shall be an array of plugin ids: --enabled_plugins='PluginId1 PluginId2 ...'.

Note that the events-into-websocket plugin runs a websocket server along with Hathor headless wallet.

2. Choose the port you want the websocket clients to connect.
3. Append --plugin_ws_port=<websocket_server_chosen_port>, replacing the <websocket_server_chosen_port> placeholder with the number of the port you want the websocket clients to connect.
4. Append -p <websocket_server_chosen_port>:<websocket_server_chosen_port> to bind the container port of the websocket server to a host port, replacing the <websocket_server_chosen_port> placeholders with the number of the chosen port.
5. Use the Docker image you built in the previous step, replacing the <docker_image_id> placeholder with its image id.

At the end of this step, the command to start the wallet application will be as follows:

docker run \
  -it -p 8000:8000 \
  -p <websocket_server_chosen-port>:<websocket_server_chosen_port> \
  <docker_image_id> \
  --seed_default '<24_words_seed_phrase_string>' \
  --network mainnet \
  --server https://node2.mainnet.hathor.network/v1a/ \
  --enabled_plugins='ws' \
  --plugin_ws_port=<websocket_server_chosen_port>

Docker compose

If you installed Hathor headless wallet along Hathor full node with Docker compose, you must modify the docker-compose.yml file to enable and configure the plugin, and use the new image you built in the previous step:

1. Open the command line from the directory where you installed Hathor headless wallet.
2. Open the docker-compose.yml file.
3. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_ENABLED_PLUGINS=ws.

If you are enabling multiple plugins, value shall be an array of plugin ids: HEADLESS_ENABLED_PLUGINS=PluginId1 PluginId2.

Note that the events-into-websocket plugin runs a websocket server along with Hathor headless wallet.

4. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_PLUGIN_WS_PORT=<websocket_server_chosen_port>, replacing the <websocket_server_chosen_port> placeholder with the number of the port you want the websocket clients to connect.

5. Use the Docker image you built in the previous step, replacing the <docker_image_id> placeholder with its image id, as the value of the image key within hathor-wallet-headless.

At the end of this step, the docker-compose.yml file will be as follows:

docker-compose.yml

hathor-core:
  ...
hathor-wallet-headless:
  image: <docker_image_id>
  ...
  environment:
    - HEADLESS_SEED_DEFAULT=<24_words_seed_phrase_string>
    - HEADLESS_NETWORK=testnet
    - HEADLESS_SERVER=http://hathor-core:8080/v1a/
    - HEADLESS_ENABLED_PLUGINS=ws
    - HEADLESS_PLUGIN_WS_PORT=<websocket_server_chosen_port>

Task completed

You have installed the events-into-websocket plugin in your instance of Hathor headless wallet and are now running a websocket server that will send all events to all its connected websocket clients.

The events-into-websocket plugin is part of the external notification feature. To know how to use this plugin or install other plugins of this feature, see Hathor external notifications.