The best way to learn and develop the HOPR protocol is by interacting with a HOPR node connected inside the HOPR network. A series of HOPR nodes fully interconnected between each other is called a HOPR cluster.
Without a HOPR cluster, app developers can only fake interactions with a HOPR node by mocking their API1, and core protocol developers can't replicate critical functionality over messaging such as ticket redemption and packet relaying.
MacOS M1 users will need to follow an extra set of instructions from NVM to allow them to use Node.js 16.
Node.js should be compiled under x64 architecute.
To run a HOPR cluster, we suggest the following options to you based on your Operating System (OS):
- Windows: Gitpod
- Linux or macOS: Gitpod or Local
The simplest and fastest way to setup a HOPR cluster is using Gitpod. Gitpod is a cloud tool used to create automated dev environments in seconds. We have configured our HOPR monorepo to quickly setup everything for you to get started.
After Gitpod creates a virtual machine with our codebase, it will immediately start running a local cluster as described by our
Gitpod configuration file. The entire setup will take roughly 5-10
minutes, after which it will
export a series of endpoint URLs which you can use later.
gitpod /workspace/hoprnet (master) $ echo $HOPR_NODE_1_HTTP_URL
gitpod /workspace/hoprnet (master) $ echo $HOPR_NODE_1_WS_URL
gitpod /workspace/hoprnet (master) $ echo $HOPR_NODE_1_ADDR
When running a HOPR cluster inside Gitpod, all the URLs will be exposed via their own DNS service, which resolves services to ports via
URLs that look like this
https://13302-hoprnet-mynechat-7x6h2ghc17f.ws-us30.gitpod.io. These URLs change every so often, and are behind
SSL certificates within Gitpod, making them susceptible to
CORS erros when working locally.
To avoid these issues, we recommend installing the Gitpod Companion App, which
will forward Gitpod's services to your workstation, so you can use them via
127.0.0.1 instead of the Gitpod URLs. As all our documentation
assume this local IP, so using the app will make things easier for you to read on.
If you do not want to use the Gitpod Companion App, just remember to replace the URLs in the documentation to your Gitpod service URL. You
can obtain the specific URL per port running the tool
gp. For knowing the URL behind port
13301 you run the following:
gp url 13301
which will return something like
https://13301-hoprnet-mynechat-7x6h2ghc17f.ws-us30.gitpod.io. Please be aware that depending on whether
the documentation refers to your
WS_URL, you might need to change the protocol from
The local setup will give you a similar setup to the one the HOPR team works with on a daily basis. After all dependencies are installed, this configuration allows you to develop HOPR apps offline.
- Download the latest version of the repository: Download a local version of our GitHub repository monorepo2
and unzip it in your local folder (roughly
~30 Mbsat the time of writing). For the next tasks, we will assume you are within that folder.
- Install the dependencies of the project and build it: Make sure you have
nodejs@16(we suggest installing it via nvm, ie
nvm install lts/gallium), and
corepack enable) to install and build the required packages and project modules. Ideally, you also have setup your computer with basic development toolset3. Please bear in mind that this process will take at least 5-10 minutes depending on your computer.
yarn && yarn build
- Run the one-line setup script: Proceed to run the following script. If you are planning to run MyneChat
alongside, then make sure to pass the
-mflag with your MyneChat instance URL. Please wait while this script creates the local blockchain network and deploys the project contracts. In average, the process can take between 2-6 minutes, depending on your computer capacity. Important, make sure to have both
jqinstalled in your computer before running the script, as both are used. Please be aware you also need a version of
5.xor superior, which in most macOS devices require an upgrade, the easiest being via
./scripts/setup-local-cluster.sh -m "http://app.myne.chat" -i scripts/topologies/full_interconnected_cluster.sh
Afterwards, a set off accounts with their respective HTTP REST API, HOPR Admin, and WebSocket interface will be displayed
in your screen. For the next steps, we recommend copying and pasting these URLs and
export them to your terminal so you can
make use of them in the following pages.
export apiToken=^^LOCAL-testing-123^^ HOPR_NODE_1_HTTP_URL=http://127.0.0.1:13301 HOPR_NODE_1_WS_URL=ws://127.0.0.1:19501 HOPR_NODE_2_HTTP_URL=http://127.0.0.1:13302 HOPR_NODE_2_WS_URL=ws://127.0.0.1:19502 HOPR_NODE_3_HTTP_URL=http://127.0.0.1:13303 HOPR_NODE_3_WS_URL=ws://127.0.0.1:19503 HOPR_NODE_4_HTTP_URL=http://127.0.0.1:13304 HOPR_NODE_4_WS_URL=ws://127.0.0.1:19504 HOPR_NODE_5_HTTP_URL=http://127.0.0.1:13305 HOPR_NODE_5_WS_URL=ws://127.0.0.1:19505
- The demo application MyneChat uses a mock server to simplify it’s development workflow. Nevertheless, to fully experience the extend of its features, it relies on a HOPR cluster, either a local or a public one.↩
- By using the
mastertag, you are downloading the latest version of
hoprnetto spin up your nodes, which might be ideal to your particular use case. However, due to the rapid development done on the project, you might be better off using a stable release. The latest stable release known at the time of writing is
- If you have installed and built another
node.jsapplication from your computer in the past, you likely will not need to do anything else. However, in the case your are only starting to develop in
node.js, there's a high chance you might need to install a few extra tools. For instance, in
Linux-based OS, you will likely also need to install
build-essentials(e.g. in Ubuntu do
apt-get install build-essentials), whereas in
macOSyou need Xcode developer tools, installable via