Install events-into-amazon-sqs plugin into headless wallet

Goal

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

The events-into-amazon-sqs plugin is part of the external notification feature. For more on 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 aws-sdk@^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 aws-sdk@^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 the installed dependencies. The image that Hathor Labs provides at Docker Hub does not come with the 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 aws-sdk@^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 'sqs' 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: ['sqs'],

  plugin_config: {},

  ...

};

4. Append the --plugin_sqs_region <aws_region> parameter into the command to start the wallet application, replacing the <aws_region> placeholder with the AWS region code of the Amazon SQS.

5. Append the --plugin_sqs_queue_url <queue_url> parameter into the command to start the wallet application, replacing the <queue_url> placeholder with the URL of the Amazon SQS queue.

6. (Optional) When developing, you may want to run a local queue. In this case, do this substep to point the aws-sdk to a local instance. Append the --plugin_sqs_endpoint_url <endpoint_url> parameter, replacing the <endpoint_url> placeholder with the endpoint of your local queue instance.

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

npm start -- --plugin_sqs_region <aws_region> --plugin_sqs_queue_url <queue_url>

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:

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

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

2. Append --plugin_sqs_region=<aws_region>, replacing the <aws_region> placeholder with the AWS region code of the Amazon SQS.

3. Append --plugin_sqs_queue_url=<queue_url>, replacing the <queue_url> placeholder with the URL of the Amazon SQS queue.

4. (Optional) When developing, you may want to run a local queue. In this case, do this substep to point the aws-sdk to a local instance. Append the --plugin_sqs_endpoint_url=<endpoint_url> parameter, replacing the <endpoint_url> placeholder with the endpoint of your local queue instance.

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 \
  <docker_image_id> \
  --seed_default '<24_words_seed_phrase_string>' \
  --network mainnet \
  --server https://node2.mainnet.hathor.network/v1a/ \
  --enabled_plugins='sqs' \
  --plugin_sqs_region=<aws_region> \
  --plugin_sqs_queue_url=<queue_url>

Docker compose

If you installed Hathor headless wallet along Hathor full node with Docker compose, you must add new lines to the docker-compose.yml file to enable and configure the plugin:

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=sqs.

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

4. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_PLUGIN_SQS_REGION=<aws_region>, replacing the <aws_region> placeholder with the AWS region code of the Amazon SQS.

5. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_PLUGIN_SQS_QUEUE_URL=<queue_url>, replacing the <queue_url> placeholder with the URL of the Amazon SQS queue.

6. (Optional) When developing, you may want to run a local queue. In this case, do this substep to point the aws-sdk to a local instance. At the end of the list of items within environment, from hathor-wallet-headless, add the key/value pair HEADLESS_PLUGIN_SQS_ENDPOINT_URL=<endpoint_url>, replacing the <endpoint_url> placeholder with the endpoint of your local queue instance.

7. 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=sqs
    - HEADLESS_PLUGIN_SQS_REGION=<aws_region>
    - HEADLESS_PLUGIN_SQS_QUEUE_URL=<queue_url>

Task completed

You have installed the events-into-amazon-sqs plugin in your instance of Hathor headless wallet.

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