Skip to main content
Version: v5.0.0

Binary

info

The HOPRd v5.0.0 binary is available for Linux only (x86_64 and aarch64). On macOS, use Docker or Docker Compose.

This guide installs the HOPRd binary in /root/hoprd and runs it as a systemd service. When you finish, the folder looks like this:

PathWhat it is
/root/hoprd/hoprdThe HOPRd binary
/root/hoprd/conf/hoprd-binary.cfg.yamlYour node configuration
/root/hoprd/conf/hopr.idYour node identity file
/root/hoprd/dataYour node database

Create your node identity, Safe and node module​

Migrating from v3.0.x?

If you came here from the migration guide, you already have your identity file and your new Safe and node module addresses. Skip to Download the HOPRd binary. In step 3.2, use your backed-up hopr.id and the identity password you used on v3.0.x.

Run these steps on any computer with Docker Desktop. This can be your node machine if it is your own computer. Don't run them on a rented or shared server, because the command in step 1.4 asks for a private key.

  1. Start Docker Desktop

    Download and start Docker Desktop on your computer.

  2. Create a temporary folder

    Create a temporary folder called hopr-identity in your home directory.

    Linux / macOS (Terminal):

    mkdir -p ~/hopr-identity

    Windows (PowerShell):

    New-Item -ItemType Directory -Force -Path "$HOME\hopr-identity"

  3. Create your node identity

    Gather the values you need for node identity creation. You'll paste these into the command.

    PlaceholderWhat it isWhere to find it
    <YOUR_IDENTITY_PASSWORD>The password that protects your node identity fileCreate a strong passphrase (refer to this guide).
    <NUMBER>How many node identities to create, one per nodeUse 1 unless you run several nodes (see Multiple nodes).

    Create your node identity. The folder path is written differently on each system.

    Linux / macOS (Terminal):

    docker run --rm -it --pull always \
    -v ~/hopr-identity:/data \
    -e IDENTITY_PASSWORD='<YOUR_IDENTITY_PASSWORD>' \
    europe-west3-docker.pkg.dev/hoprassociation/docker-images/hopli:latest \
    identity create \
    --identity-directory /data \
    --identity-prefix hopr \
    --number <NUMBER>

    Windows (PowerShell):

    docker run --rm -it --pull always `
    -v "$HOME\hopr-identity:/data" `
    -e 'IDENTITY_PASSWORD=<YOUR_IDENTITY_PASSWORD>' `
    europe-west3-docker.pkg.dev/hoprassociation/docker-images/hopli:latest `
    identity create `
    --identity-directory /data `
    --identity-prefix hopr `
    --number <NUMBER>

    The command creates one file per identity in the hopr-identity folder: hopr0.id, hopr1.id, and so on.

  4. Create your Safe and node module

    Gather the values you need for Safe and node module creation. You'll paste these into the command.

    PlaceholderWhat it isWhere to find it
    <YOUR_IDENTITY_PASSWORD>The password that protects your node identity fileThe password you set in previous step during node identity creation.
    <YOUR_RPC_PROVIDER_URL>The URL of a Gnosis Chain RPC endpointSee the Custom RPC provider guide.
    <SAFE_OWNER>The address of the wallet that owns your Safe wallet.Your wallet app, for example Rabby wallet, MetaMask.
    important

    Before you run the command, create a new burner wallet (a fresh wallet with no other funds) and send it 0.02 xDai. The command asks for this wallet's private key and uses it only to pay the transaction fees. Your new Safe is owned by your <SAFE_OWNER> wallet, not the burner wallet, so you never need to paste your Safe owner's private key.

    Create your Safe and node module, and add the node identity you just created to them. The folder path is written differently on each system.

    Linux / macOS (Terminal):

    docker run --rm -it --pull always \
    -v ~/hopr-identity:/data \
    -e IDENTITY_PASSWORD='<YOUR_IDENTITY_PASSWORD>' \
    europe-west3-docker.pkg.dev/hoprassociation/docker-images/hopli:latest \
    safe-module create \
    --network piz-palu-prod \
    --provider-url <YOUR_RPC_PROVIDER_URL> \
    --admin-address <SAFE_OWNER> \
    --identity-directory /data \
    --allowance 15000000000000000000000

    Windows (PowerShell):

    docker run --rm -it --pull always `
    -v "$HOME\hopr-identity:/data" `
    -e 'IDENTITY_PASSWORD=<YOUR_IDENTITY_PASSWORD>' `
    europe-west3-docker.pkg.dev/hoprassociation/docker-images/hopli:latest `
    safe-module create `
    --network piz-palu-prod `
    --provider-url <YOUR_RPC_PROVIDER_URL> `
    --admin-address <SAFE_OWNER> `
    --identity-directory /data `
    --allowance 15000000000000000000000

    • At the Enter private key: prompt, paste the private key of your burner wallet and press Enter. Nothing appears on screen while you paste, which is expected.

    • hopli sends the transactions. When it finishes, the last two lines show your new safe and node_module addresses. Write both down, because you need them in step 3.2. Example:

      safe 0xAbC0000000000000000000000000000000000123
      node_module 0xDeF0000000000000000000000000000000000456

  5. Move the identity file to your node machine

    On your node machine, create the node folder:

    sudo mkdir -p /root/hoprd/conf
    • In the temporary hopr-identity folder, rename the identity file hopr0.id to hopr.id, then move it to /root/hoprd/conf/ on your node machine.
    • Once hopr.id is in /root/hoprd/conf/, keep a backup copy of it somewhere safe outside the node folder, then delete the temporary hopr-identity folder.

Download the HOPRd binary​

  1. Find your machine architecture

    On your node machine, run:

    uname -m
    OutputFile to download
    x86_64hoprd-x86_64-linux
    aarch64 or arm64hoprd-aarch64-linux

  2. Download the binary and check it

    Replace <ARCH> with x86_64 or aarch64 from the previous step:

    curl -fLO https://github.com/hoprnet/hoprd/releases/download/v5.0.0/hoprd-<ARCH>-linux
    curl -fLO https://github.com/hoprnet/hoprd/releases/download/v5.0.0/hoprd-<ARCH>-linux.sha256
    sha256sum hoprd-<ARCH>-linux
    cat hoprd-<ARCH>-linux.sha256

    The two checksums must match. If they don't, delete the file and download it again.

    All files are on the HOPRd v5.0.0 release page.

  3. Install the binary

    Move the binary into the node folder, name it hoprd and make it executable:

    sudo mv hoprd-<ARCH>-linux /root/hoprd/hoprd
    sudo chmod +x /root/hoprd/hoprd

Configure your node​

  1. Download the configuration file

    sudo curl -fL -o /root/hoprd/conf/hoprd-binary.cfg.yaml https://docs.hoprnet.org/files/hoprd-docker.cfg.yaml

  2. Fill in your values

    Open the file:

    sudo vim /root/hoprd/conf/hoprd-binary.cfg.yaml

    Set these values. The other settings work as they are.

    SettingWhat to enter
    identity.file/root/hoprd/conf/hopr.id
    db.data/root/hoprd/data
    identity.passwordThe identity password from step 1.3.
    api.authA secret token for the REST API, at least 8 characters. See this guide.
    hopr.host.address.IPv4Your public IP address. If you use a DDNS hostname, see hopr.host.
    hopr.safe_module.safe_addressThe safe address from step 1.4.
    hopr.safe_module.module_addressThe node_module address from step 1.4.

    If your node runs behind a router, forward port 9091 (TCP and UDP) to it. See the port forwarding guide. For the other settings, see Understanding configuration file settings.

  3. Check your configuration

    Download the configuration checker for your architecture and run it:

    curl -fLO https://github.com/hoprnet/hoprd/releases/download/v5.0.0/hoprd-cfg-<ARCH>-linux
    chmod +x hoprd-cfg-<ARCH>-linux
    sudo ./hoprd-cfg-<ARCH>-linux --validate /root/hoprd/conf/hoprd-binary.cfg.yaml

    If the command prints nothing, your configuration is valid. Otherwise it prints what to fix.

Run HOPRd with systemd​

important

You need root access to set up the systemd service. If you don't have it, you can use a process manager like tmux instead.

  1. Create the service file

    sudo vim /etc/systemd/system/hoprd.service

    Paste this configuration and save the file:

    [Unit]
    Description=HOPRd Node Service
    After=network.target

    [Service]
    Type=simple
    User=root
    ExecStart=/root/hoprd/hoprd
    Restart=on-failure
    RestartSec=5

    Environment="HOPRD_CONFIGURATION_FILE_PATH=/root/hoprd/conf/hoprd-binary.cfg.yaml"

    WorkingDirectory=/root/hoprd/
    StandardOutput=journal
    StandardError=journal

    [Install]
    WantedBy=multi-user.target

  2. Reload systemd

    Run this after you create or change the service file:

    sudo systemctl daemon-reload

  3. Start HOPRd on boot

    sudo systemctl enable hoprd

  4. Start HOPRd

    sudo systemctl start hoprd

  5. Check the service status

    sudo systemctl status hoprd

    The status should show active (running). If it doesn't, see View logs.

Fund your node​

  1. Fund your Safe wallet

    Migrating from v3.0.x?

    Skip this step. You moved your wxHOPR to your new Safe in the migration guide.

    Send at least 1 wxHOPR to your Safe wallet: the safe address from step 1.4. Your node uses it to pay the fee for announcing itself on the network when it starts.

  2. Fund your node with xDai

    When the node starts, it shows its address and waits until it has xDai. To find the address, run:

    sudo journalctl -u hoprd | grep "blockchain_address"

    The value of blockchain_address is your node address. Send at least 0.01 xDai to it. The node checks its balance regularly and finishes starting once the funds arrive.

Check that your node is running​

  1. Check that the node announced itself

    sudo journalctl -u hoprd -f

    Look for node announced successfully or node already announced on chain. Press Ctrl+C to stop following the logs. The node keeps running.

  2. Check that the node is ready

    curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3001/readyz

    200 means your node is running, connected to the network and to the chain. 412 means it's still starting; wait a few minutes and try again.

  3. Check your node address through the API

    Replace <YOUR_API_TOKEN> with the api.auth token from step 3.2:

    curl -s -H "X-Auth-Token: <YOUR_API_TOKEN>" http://localhost:3001/api/v4/account/addresses

    The response shows your node address, for example {"native":"0x07eaf07d6624f741e04f4092a755a9027aaab7f6"}.

Your node is running

To verify that it's working properly, follow this guide.

To start, stop, upgrade or uninstall your node, see Managing Node Service.

Fund your channels for Cover Traffic​

Once your node works as expected, change the channel funding values in your configuration file to get full Cover Traffic rewards, as described in Fund your channels for Cover Traffic. With the default values, your node doesn't keep enough wxHOPR in its channels to be eligible for Cover Traffic.

Table of Contents