Skip to main content

Install core (full node) and headless wallet using Docker compose

Goal​

By the end of this guide, you will have a Hathor full node and a headless wallet running as Docker Compose services, with both accessible via API on localhost.

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

Requirements​

Hardware​

For production environment:

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

Reference machine: AWS EC2 type r6g.large

Software​

Platform:

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. Change the working directory to where you want to install the applications — namely, configuration file and database.
  3. Create the directory data, to store the application database (mainly the blockchain).

Step 2: set up configurations​

The headless wallet service requires a 24-word seed phrase to derive the wallet. If you already have a seed phrase you want to use, skip the next substep.

  1. (Optional) If you don't have a wallet seed phrase, generate a new one:
docker run --rm --entrypoint /bin/sh \
  hathornetwork/hathor-wallet-headless \
  -c "make 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 of the seed phrase (either digital, physical, or both) and ensuring that both the backup and the chosen installation directory are protected against unauthorized access.

  1. Create the file docker-compose.yml.
  2. Write the following configurations, replacing the placeholder <24_words_seed_phrase_string> with the seed phrase (without quotation marks):
<working_directory>/docker-compose.yml
networks:
  hathor:
    driver: bridge
    name: hathor
services:
  full-node:
    image: hathornetwork/hathor-core
    ports:
      - "8080:8080"
    volumes:
      - ${PWD}/data:/data
    environment:
      - HATHOR_TESTNET=true
      - HATHOR_DATA=/data
      - HATHOR_STATUS=8080
      - HATHOR_WALLET_INDEX=true
      - HATHOR_CACHE=true
      - HATHOR_CACHE_SIZE=100000
    networks:
      hathor:
        aliases:
          - full-node
    command: run_node
    healthcheck:
      test: ["CMD", "sh", "-c", "timeout 1 bash -c 'echo > /dev/tcp/localhost/8080'"]
      start_period: 2s
      timeout: 2s
      retries: 10
      interval: 2s
  wallet:
    image: hathornetwork/hathor-wallet-headless
    depends_on:
      full-node:
        condition: service_healthy
    ports:
      - "8000:8000"
    environment:
      - HEADLESS_NETWORK=testnet
      - HEADLESS_SERVER=http://full-node:8080/v1a/
      - HEADLESS_SEED_DEFAULT=<24_words_seed_phrase_string>
      - HEADLESS_HTTP_PORT=8000
    networks:
      hathor:
        aliases:
          - wallet
    healthcheck:
      test: ["CMD", "sh", "-c", "timeout 1 nc -z 0.0.0.0 8000"]
      start_period: 2s
      timeout: 2s
      retries: 10
      interval: 2s

:::note Adding more configuration options

Any option available to the full node or headless wallet can be added to the environment section of docker-compose.yml by converting CLI flags to environment variables:

  • Full node: --some-flag → HATHOR_SOME_FLAG
  • Headless wallet: --some-flag → HEADLESS_SOME_FLAG

For example: --data → HATHOR_DATA, --gap_limit → HEADLESS_GAP_LIMIT.

:::

Step 3: start the containerized applications​

  1. Start the docker compose service:
docker compose up

The previous command will launch containers for the full node and the 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 full node connects to other peers of Hathor Network testnet and starts syncing its ledger with theirs — i.e., all blocks and transactions ever recorded in Hathor blockchain testnet.

You may keep this terminal open to monitor the full node's output log. This allows you to confirm that the blockchain is receiving new blocks correctly and to check for any errors when executing API requests.

  1. Open a new terminal.
  2. Verify if both applications have started correctly:
docker ps

Both containers must be running and their STATUS should be marked as (healthy). Note that this health check only confirms that both applications have been initialized and are running. It does not detect behavioral failures, nor does it serve as continuous monitoring.

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 full node on Hathor Network testnet, listening for API requests on port 8080, and a running instance of headless wallet listening for API requests on port 8000, both of localhost. 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 ledger (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 with a snapshot.

:::tip Connecting other containers to the stack

To integrate other containers with the full node and headless wallet, add them to the hathor Docker network defined in docker-compose.yml:

docker network connect hathor <other_docker_container>

You can then reference the services by name — e.g., http://full-node:8080 or http://wallet:8000.

:::

Finally, here we used the minimal configuration to have an operational full node. To set up your full node according to your environment and use case, see Configuration at Full node pathway.

What's next?​