Skip to main content
Version: v5.0.0

Docker Compose

Setting up a HOPR node with Docker Compose is intended for advanced users. It provides a sophisticated setup, allowing the use of a configuration file and node monitoring tools to enhance the node management experience.

Install Docker, Docker Compose and unzip​

Your node machine needs Docker Engine, the Docker Compose plugin, and the curl and unzip tools. Install them on the machine where you will run your node.

Already running a node with Docker Compose?

If you are migrating from v3.0.x, Docker and Docker Compose are already installed. Run the commands in the last step to check that docker compose and unzip work, then continue with Create your node identity, Safe and node module.

  1. Install Docker Engine and Docker Compose

    Follow the official guide for your distribution. Each guide installs Docker Engine together with the Docker Compose plugin (docker-compose-plugin).

  2. Install curl and unzip

    Ubuntu / Debian:

    sudo apt-get update && sudo apt-get install -y curl unzip

    Fedora / CentOS:

    sudo dnf install -y curl unzip

  3. Allow your user to run Docker

    The commands in this guide run docker without sudo. Add your user to the docker group:

    sudo usermod -aG docker $USER

    Log out and log back in (or reconnect via SSH) for the change to take effect. Members of the docker group have root-level access to the machine, so only add users you trust. If you prefer not to do this, add sudo in front of every docker command in this guide.

  4. Check the installation

    Run these commands. Each one should print a version number:

    docker --version
    docker compose version
    unzip -v | head -1

    If docker compose version fails, the Docker Compose plugin is missing. The older docker-compose command (with a hyphen) is not used in this guide.

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 compose folder.

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 2.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. Example:

      safe 0xAbC0000000000000000000000000000000000123
      node_module 0xDeF0000000000000000000000000000000000456

  5. Write down your Safe and node module addresses

    Write down the safe and node_module addresses. You will enter them in Configure your node.

  6. Keep your identity file and password

    Keep the hopr0.id file and its password. You will copy the file to your node machine in Manage the identity file, and enter the password in Set up secrets environment variables.

Download compose folder​

Start by downloading the compose folder from the HOPR repository to the machine where you will run your node. Run the command in your home folder (or wherever you want the compose folder to live). It needs curl and unzip from Install Docker, Docker Compose and unzip:

curl -fL -o v5.0.0.zip https://github.com/hoprnet/hoprd/archive/refs/tags/v5.0.0.zip && \
  unzip v5.0.0.zip "hoprd-5.0.0/deploy/compose/*" -d extracted_files && \
  mv extracted_files/hoprd-5.0.0/deploy/compose . && \
  rm -rf v5.0.0.zip extracted_files

Set up environment variables​

Inside the compose folder, rename .env.sample to .env:

mv .env.sample .env

Adjust the following environment variables in the .env file:

  • HOPRD_IMAGE:
    Sets the HOPRd Docker image. Default is europe-west3-docker.pkg.dev/hoprassociation/docker-images/hoprd:stable, the current release. You don't need to change it.

  • HOPRD_API_PORT:
    Sets the port on your machine that forwards to your node's REST API. Default is 3001.
    Inside the container, the API always listens on port 3001.

  • HOPRD_P2P_PORT:
    Sets the peer-to-peer communication port. Default is 9091.
    If you plan to run your node behind NAT (e.g., at home or in an office), you must expose port 9091 to the public so other nodes can connect.

    For help, see our port forwarding guide. This port must remain open to allow external peer connections.

Set up secrets environment variables​

Inside the compose folder, rename .env-secrets.sample to .env-secrets:

mv .env-secrets.sample .env-secrets

Adjust the following secrets environment variables in the .env-secrets file:

  • HOPRD_PASSWORD:
    Enter the password you set when you created your node identity. If you are migrating, use the same password you used on v3.0.x. Make sure to write it down, as you will need it if you ever need to restore your node in the future.

  • HOPRD_API_TOKEN:
    Enter your own secret token. You need it to access your node's API. For guidance on how to create a secure token, see this guide.

Configure your node​

Inside the compose folder, navigate to the hoprd/conf subfolder and open the hoprd.cfg.yaml file. Set these values:

  • blokli_url: change https://blokli.prod.hoprnet.link to https://blokli.piz-palu.gnosisvpn.io.
  • hopr.host.address.IPv4: your public IP address (replace 127.0.0.1).
  • hopr.host.port: the value of HOPRD_P2P_PORT (default 9091).
  • hopr.safe_module.safe_address: the safe address you created.
  • hopr.safe_module.module_address: the node_module address you created.

For details, see the configuration guidelines under the Docker Compose section.

Manage the identity file​

Copy your identity file into the compose/hoprd/conf folder on your node machine and rename it to hopr.id:

  • New node: the hopr0.id file from the hopr-identity folder. After copying, keep a backup of hopr.id somewhere safe outside the node folder, then delete the temporary hopr-identity folder.
  • Migrating from v3.0.x: your backed-up hopr.id.

Fund your Safe wallet​

Migrating from v3.0.x?

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

Send at least 1 wxHOPR to your Safe wallet: the safe address you created in Create your node identity, Safe and node module. Your node uses it to pay the fee for announcing itself on the network when it starts.

Launch Docker Compose​

Inside the compose folder, start your node with the hoprd profile:

COMPOSE_PROFILES=hoprd docker compose up -d

Fund your node with xDai​

When the node starts, it shows its address and waits until it has xDai.

  1. Find your node address

    On the machine where you run your node, execute:

    docker logs hoprd 2>&1 | grep "blockchain_address"

    The value of blockchain_address is your node address.

  2. Send xDai to your node

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

  3. Check that the node started

    Check the logs:

    docker logs -f hoprd

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

note

Until both the Safe and the node are funded, the node may stop and restart a few times. This is expected and stops once the funds arrive.

Your node is running

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

If you are migrating from v3.0.x, go back to the migration guide and continue with Verify and clean up.

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