Summary

Hedera Local Node is an easy-to-deploy, minimal topology Hedera network. It is designed for use in development, including testing smart contracts locally.

Hedera Local Node deploys with a single consensus node and mirror node each, as well as supporting services. These include Prometheus and Grafana for observability, and the Mirror Node Explorer web app, which allows users to view data about blocks, transactions, accounts, and more.

This tutorial will guide you through the process of installing and deploying Hedera Local Node, and describe the environment variables you’ll need to start interacting with your locally deployed Hedera network.

Contents

Prerequisites

A machine must have the following tools, available resources, and configuration to run Hedera Local Node.

Software requirements

  • Docker: Version 20.10.x or greater
  • Docker Compose: Version 2.12.3 or greater
  • Node.js: Version 14.x or greater
  • NPM: Version 6.14.17 or greater

Tip: Verify that your environment has the correct versions by running the following commands:

node -v          # Check Node.js version
npm -v           # Check NPM version
docker -v        # Check Docker version
docker compose version  # Check Docker Compose version

Resource requirements

Your machine must have at the following resources available:

  • System RAM: 16GB
  • CPUs: 6
  • Memory: 8GB
  • Swap: 1GB
  • Disk Image Size: 64GB

Docker configuration

  1. On a mac environment, Docker has user-configurable resource limits. Ensure that the minimum required resources are available by configuring your Resources settings for CPU, Memory, Swap, and Disk Image Size in the Docker desktop app.

  2. In addition, the following advanced settings must be enabled:

    • File Sharing: Enable VirtioFS file sharing.
    • Docker Sockets: Allow the default Docker sockets to be used.

Install Hedera Local Node

Hedera Local Node can be installed in two ways:

  1. As an official NPM release. This is the easiest option, and likely suitable for most users who want to test and develop applications to run against Hedera.
  2. By building from the source code, which is hosted on GitHub. This allows for more customization of the deployment, and is required if you need to test against a particular Git branch or tag, or if you want to contribute to the project.

Option 1: Install as NPM package

Download and install the latest official NPM release of Hedera Local Node. The -g flag will create a global symlink, allowing you to run hedera CLI commands anywhere on your machine.

npm install @hashgraph/hedera-local -g

Option 2: Build from Source

First, clone the Hedera Local Node Git repository from where it hosted on GitHub. Then cd into the directory and check out whatever version you want to deploy.

git clone https://github.com/hashgraph/hedera-local-node.git
cd hedera-local-node
git checkout <DESIRED SOURCE VERSION>

Windows users only: update the file endings for the initialization script:

dos2unix compose-network/mirror-node/init.sh

Customize your deployment

  1. Your Hedera Local Node deployment is configured in the .env file. The following resource limits can be set:

    Platform:

    • PLATFORM_JAVA_HEAP_MIN: JVM minimum heap memory allocated.
    • PLATFORM_JAVA_HEAP_MAX JVM heap limit.

    Consensus node:

    • NETWORK_NODE_MEM_LIMIT: memory limit for network node.

    Mirror node:

    • MIRROR_GRPC_MEM_LIMIT: memory limit for mirror node gRPC.
    • MIRROR_IMPORTER_MEM_LIMIT: memory limit for mirror node importer.
    • MIRROR_REST_MEM_LIMIT: memory limit for mirror node rest api.
    • MIRROR_WEB3_MEM_LIMIT: memory limit for mirror node web3.

  2. To change application.properties, api-permission.properties, or bootstrap.properties properties, update the APPLICATION_CONFIG_PATH to the location of updated config folder in .env file.

  3. Your Local Node deployment also depends on the following supporting files:

    • compose-network: Contains static files for starting the local network.
    • compose-network/grafana/dashboards: Grafana dashboard definitions (JSON format).
    • compose-network/grafana/datasources: Grafana datasource definitions (YAML format).
    • network-logs: Created at runtime, contains log files generated after starting Local Node.

Install globally with NPM

The following command creates a global symlink, allowing you to run hedera CLI commands from anywhere on your machine:

npm install && npm install -g

Deploy Hedera Local Node

Option 1: Use the hedera CLI

The hedera CLI allows you to start, restart, and stop your Local Node deployment, as well as create accounts.

Start the network

Run hedera start to trigger the Docker deployment of Hedera. Examine the logs to make sure there are no errors. See Troubleshooting if you run into any problems.

After deployment, you can [Inspect your deployed Hedera Local Node] with the Mirror Node Explorer.

TIP: The --accounts flag can be used to change the number of accounts created from the default value of 10.

:) hedera start
[Hedera-Local-Node] INFO (StateController) [✔︎] Starting start procedure!
[Hedera-Local-Node] INFO (InitState) ⏳ Making sure that Docker is started and it is correct version...
[Hedera-Local-Node] INFO (DockerService) ⏳ Checking docker compose version...
[Hedera-Local-Node] INFO (DockerService) ⏳ Checking docker resources...
[Hedera-Local-Node] INFO (InitState) ⏳ Setting configuration with latest images on host 127.0.0.1 with dev mode turned off using turbo mode in single node configuration...
[Hedera-Local-Node] INFO (InitState) [✔︎] Local Node Working directory set to /Users/michaeltrestman/Library/Application Support/hedera-local.
[Hedera-Local-Node] INFO (InitState) [✔︎] Hedera JSON-RPC Relay rate limits were disabled.
[Hedera-Local-Node] INFO (InitState) [✔︎] Needed environment variables were set for this configuration.
[Hedera-Local-Node] INFO (InitState) [✔︎] Needed bootsrap properties were set for this configuration.
[Hedera-Local-Node] INFO (InitState) [✔︎] Needed bootsrap properties were set for this configuration.
[Hedera-Local-Node] INFO (InitState) [✔︎] Needed mirror node properties were set for this configuration.
[Hedera-Local-Node] INFO (StartState) ⏳ Starting Hedera Local Node...

Create accounts

Use hedera generate-accounts <num> to create a specified number of accounts.

:) hedera generate-accounts 2

[Hedera-Local-Node] INFO (StateController) [✔︎] Starting accountCreation procedure!
[Hedera-Local-Node] INFO (AccountCreationState) ⏳ Starting Account Creation state in synchronous mode ...

Restart the network

Run hedera restart to shutdown and re-initialize Hedera. Note that all data will be lost.

Stop the network

Shut down the network with hedera stop.

:) hedera stop
[Hedera-Local-Node] INFO (StateController) [✔︎] Starting stop procedure!
[Hedera-Local-Node] INFO (StopState) ⏳ Initiating stop procedure. Trying to stop docker containers and clean up volumes...
[Hedera-Local-Node] INFO (StopState) ⏳ Stopping the network...
[Hedera-Local-Node] INFO (StopState) [✔︎] Hedera Local Node was stopped successfully.

Option 2: Use docker compose

If you built Hedera Local Node from source code, you can issue commands to Docker directly, which is what the Hedera CLI does under the hood.

Start the network

Run docker compose up to deploy your Hedera Local Node network, or docker compose up -d to run it in the background.

:) docker compose up -d
 
[+] Running 27/27
 ⠿ Network network-node-bridge          Created                                      0.1s
 ⠿ Network cloud-storage                Created                                      0.1s
 ⠿ Network hedera-local-node_default    Creat...                                     0.1s
 ⠿ Network mirror-node                  Created                                      0.1s
 ⠿ Volume "prometheus-data"             Created                                      0.0s
 ⠿ Volume "mirror-node-postgres"        Created                                      0.0s
 ⠿ Volume "minio-data"                  Created                                      0.0s
 ⠿ Volume "grafana-data"                Created                                      0.0s
 ⠿ Container prometheus                 Started                                      1.5s
 ⠿ Container relay-cache                Started                                      1.7s
 ⠿ Container minio                      Started                                      1.3s
 ⠿ Container envoy-proxy                Started                                      1.8s
 ⠿ Container haveged                    Started                                      0.8s
 ⠿ Container hedera-explorer            Started                                      1.3s
 ⠿ Container grafana                    Started                                      1.5s
 ⠿ Container mirror-node-db             Started                                      1.1s
 ⠿ Container account-balances-uploader  Sta...                                       2.0s
 ⠿ Container record-streams-uploader    Start...                                     2.1s
 ⠿ Container record-sidecar-uploader    Start...                                     1.9s
 ⠿ Container mirror-node-importer       Started                                      2.2s
 ⠿ Container network-node               Healthy                                     33.3s
 ⠿ Container mirror-node-rest           Started                                      2.8s
 ⠿ Container mirror-node-web3           Started                                      2.9s
 ⠿ Container json-rpc-relay             Started                                     34.5s
 ⠿ Container mirror-node-grpc           Started                                      3.1s
 ⠿ Container json-rpc-relay-ws          Started                                     34.6s
 ⠿ Container mirror-node-monitor        Started                                     34.5s

Stop the network

To shut down your deployment, hit ctrl-c once to initialize the shutdown but allow it to finish gracefully. If it is running in the background, run docker compose down -v to initialize the shutdown and view the logs as it completes.

:) docker compose down -v

+] Running 27/27
 ⠿ Container json-rpc-relay-ws          Removed                                      1.9s
 ⠿ Container account-balances-uploader  Rem...                                      10.6s
 ⠿ Container prometheus                 Removed                                      1.1s
 ⠿ Container mirror-node-monitor        Removed                                     11.4s
 ⠿ Container hedera-explorer            Removed                                     10.7s
 ⠿ Container grafana                    Removed                                      1.1s
 ⠿ Container envoy-proxy                Removed                                      0.7s
 ⠿ Container mirror-node-web3           Removed                                      1.5s
 ⠿ Container json-rpc-relay             Removed                                      1.8s
 ⠿ Container relay-cache                Removed                                      1.1s
 ⠿ Container record-sidecar-uploader    Remov...                                    10.8s
 ⠿ Container mirror-node-rest           Removed                                     10.8s
 ⠿ Container mirror-node-grpc           Removed                                      3.2s
 ⠿ Container network-node               Removed                                     11.7s
 ⠿ Container mirror-node-importer       Removed                                     10.6s
 ⠿ Container haveged                    Removed                                      0.2s
 ⠿ Container record-streams-uploader    Remov...                                    10.3s
 ⠿ Container mirror-node-db             Removed                                      0.4s
 ⠿ Container minio                      Removed                                      0.3s
 ⠿ Volume mirror-node-postgres          Removed                                      0.3s
 ⠿ Volume prometheus-data               Removed                                      0.6s
 ⠿ Volume minio-data                    Removed                                      0.6s
 ⠿ Volume grafana-data                  Removed                                      0.6s
 ⠿ Network network-node-bridge          Removed                                      0.4s
 ⠿ Network hedera-local-node_default    Remov...                                     0.3s
 ⠿ Network mirror-node                  Removed                                      0.6s
 ⠿ Network cloud-storage                Removed                                      0.4s

Clean up deployment artifacts

Run git clean -xfd; git reset --hard to remove any manually generated files, restoring a clean state for your next deployment. Be sure to copy out any desired changes to another directory before running this command.

Deployment details

Your deployment will be configured by default with the following values

Privileged account

By default, the following account can be used to pay for transactions and execute queries:

  • Account ID: 0.0.2
  • Account Key: 302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137

Consensus node

  • Consensus Node Endpoint: 127.0.0.1:50211
  • Consensus Node Account ID: 0.0.3

JSON RPC Relay

  • Synchronous request endpoint: 127.0.0.1:7546
  • Websocket endpoint for async requests: 127.0.0.1:8546

Mirror node

  • Mirror Node Explorer: 127.0.01:8080/devnet/dashboard
  • Mirror Node GRPC Endpoint: 127.0.0.1:5600
  • Mirror Node REST API Endpoint: 127.0.0.1:5551

Observability

  • Prometheus UI: 127.0.0.1:9090
  • Grafana UI: 127.0.0.1:3000
  • Grafana username: admin
  • Grafana password: admin

Note: You can create new dashboards using the Grafana visual editor and export them as JSON. To restore them when restarting the network, put the JSON files under compose-network/grafana/dashboards.

Next steps

Inspect your deployed Hedera network

To view the workings of your running Hedera Local Node deployment, open up the Mirror Node Explorer dashboard in your browser by visiting http://localhost:8080/devnet/dashboard. This app allows you to browse tokens, transactions, blocks, accounts, and more, for your local Hedera network and also for Hedera’s Main, Test, and Preview networks.

Note the network tab in the upper right-hand corner. This may default to mainnet, displaying information for the Hedera main network. Select LOCALNET (or ensure that devnet is in your URL) to view your locally deployed network.

assets/net-tab.png

Set up your local network client

Now that you have deployed a local Hedera network, you are ready to submit transactions, and develop and test Web3 applications against it. To get started, follow this tutorial on setting up and using a Hedera client, using the language-specific SDK of your choice.