Skip to main content

How to install Hathor full node and headless wallet with Docker compose

Goal​

This article will guide you to install Hathor core and Hathor headless wallet together, with Docker compose.

Hathor core is the official and reference client for operating a full node in Hathor Network.

Requirements​

Hardware​

  • CPU: 2 vCPU
  • Memory: 16 GB
  • Disk: 20 GB
  • Bandwidth: 10 Gbps

Software​

Step-by-step​

  1. Set up the environment.
  2. Set up configurations.
  3. Start the containerized applications.

Step 1: set up the environment​

  1. Start a shell session.
  2. Run the command to start Docker service:
systemctl start docker
  1. Change the working directory to where you want to store the application — namely, configuration file and database.
  2. Create the data directory, to store the application database (mainly the blockchain).

Step 2: set up configurations​

The configuration file of Docker compose requires you to provide a seed phrase that defines a wallet. If you already have a previously generated seed phrase (i.e., wallet), you may use it. Otherwise, you must generate a new seed phrase.

  1. (Optional) If you don't have a wallet seed phrase, run the command to generate a new one:
docker run --rm --entrypoint npm \
  hathornetwork/hathor-wallet-headless \
  run generate_words

The output will be a string of 24 random words.

danger

Anyone with access to a seed phrase can manage the funds of the associated wallet. Also, you cannot manage your wallet without access to the seed phrase or the private keys generated from it. Thus, we strongly recommend storing a backup file (either digital or physical or both) of the seed phrase and keeping the backup and the chosen installation directory secure against unauthorized access.

  1. Create the docker-compose.yml file.
  2. Write the following configurations, replacing the placeholders:
  • <24_words_seed_phrase_string> with the seed phrase (without quotation marks); and
  • <absolute_path_hathor_full_node> with the absolute path of the (current) working directory (parent of data).
<absolute_path_hathor_installation>/docker-compose.yml
services:
  hathor-core:
    image: hathornetwork/hathor-core
    command: run_node
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - <absolute_path_hathor_full_node>/data:/data
    environment:
      - HATHOR_TESTNET=true
      - HATHOR_STATUS=8080
      - HATHOR_STRATUM=8081
      - HATHOR_WALLET_INDEX=true
      - HATHOR_CACHE=true
      - HATHOR_CACHE_SIZE=100000
      - HATHOR_DATA=/data
  hathor-wallet-headless:
    image: hathornetwork/hathor-wallet-headless
    command: run_node
    ports:
      - "8000:8000"
    environment:
      - HEADLESS_SEED_DEFAULT=<24_words_seed_phrase_string>
      - HEADLESS_NETWORK=testnet
      - HEADLESS_SERVER=http://hathor-core:8080/v1a/
      - HEADLESS_HTTP_PORT=8000

Beyond those, you can add any element available to Hathor full node, and Hathor headless wallet configuration in their respective environment sections of docker-compose.yml. To do this, you must convert the command option format to the environment variable format. In case of Hathor full node, --some-arbitrary-configuration becomes HATHOR_SOME_ARBITRARY_CONFIGURATION. In case of Hathor headless wallet, --some-arbitrary-configuration becomes HEADLESS_SOME_ARBITRARY_CONFIGURATION. For example, --data from the full node becomes HATHOR_DATA, --gap_limit from the headless wallet becomes HEADLESS_GAP_LIMIT, and so forth.

Step 3: start the containerized applications​

Run the command to start the docker compose service:

docker compose up

The previous command will launch containers for Hathor full node and Hathor headless wallet, based on the respective images tagged as latest, originated from their respective repositories at Docker Hub, and available in your Docker local environment. If there is no image available from this source for some of them, it automatically pulls the latest one.

Your Hathor full node connects to other peers of Hathor Network testnet and starts syncing its database with theirs — i.e., all blocks and transactions ever recorded in Hathor blockchain testnet.

Task completed​

In the browser, you can use the URL http://localhost:8080/v1a/status/ to monitor the status of your full node.

You now have a running instance of Hathor full node in Hathor Network testnet, listening for API requests at port 8080, and a running instance of Hathor headless wallet listening for API requests at port 8000. Note that your full node cannot receive API requests or participate in network consensus while it is not synced with its peers. Syncing is an ongoing process that is part of the operations of a full node. However, reaching synchronization with Hathor Network starting from an empty database (from genesis block) takes on average 10 hours for testnet and 24 hours for mainnet. If you want to expedite this process, see How to bootstrap from a snapshot.

Finally, here we used the minimal configuration to have an operational full node. For a custom setup, see Hathor full node configuration.

What's next?​