Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: simplify README file #918

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore: simplify README file #918

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions DOCKER-REQUIREMENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Requirements

- [Node.js](https://nodejs.org/) `>= v20.11.0`
- Node version check: `node -v`
- NPM `>= v10.2.4`
- NPM version check: `npm -v`
- [Docker](https://www.docker.com/) `>= v27.3.1`
- Docker version check: `docker -v`
- [Docker Compose](https://docs.docker.com/compose/) `=> v2.29.7`
- Docker Compose version check: `docker compose version`
- Minimum 16GB RAM

### Note:

- Ensure the **VirtioFS** file sharing implementation is enabled in the docker settings

**Note**: The image may look different if you are on a different version
![docker-compose-settings.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/docker-compose-settings.png)

- Ensure the following configurations are set at minimum in Docker **Settings -> Resources** and are available for use.
- **CPUs:** 6
- **Memory:** 8 GB
- **Swap:** 1 GB
- **Disk Image Size:** 64 GB

**Note**: The image may look different if you are on a different version
![settings.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/settings.png)

- Ensure the hedera-local-node folder is added to Docker File Sharing **Settings -> Resources -> File Sharing**.
- If you're using hedera-local as npm package - running 'npm root -g' should output the path you have to add under File Sharing Docker's Setting.
- If you're using hedera-local as cloned repo - running 'pwd' in the project's root should output the path you have to add under File Sharing Docker's Setting.

**Note**: The image may look different if you are on a different version
![docker-file-sharing-settings.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/docker-file-sharing-settings.png)

- Ensure the *Allow the default Docker sockets to be used (requires password)* is enabled in Docker **Settings -> Advanced**.

**Note**: The image may look different if you are on a different version
![docker-socket-setting.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/docker-socket-settings.png)
116 changes: 116 additions & 0 deletions DOCKER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@

# Docker

> **_NOTE:_** This will not create accounts on startup, nor will perform any kind of checks.

## Start Your Local Network

1. Clone the `hedera-local-node` repo

```bash
git clone https://github.com/hashgraph/hedera-local-node.git
```

2. CD to the hedera-local-node directory

```bash
cd hedera-local-node
```

For Windows users: You will need to update the file endings of `compose-network/mirror-node/init.sh` by running this in WSL:

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

3. Run `docker compose up -d` from the terminal to get the network up and running
4. Set-up your local network client by following this [tutorial](https://docs.hedera.com/guides/docs/sdks/set-up-your-local-network)

## Stop Your Local Network

1. Run `docker compose down -v; git clean -xfd; git reset --hard` to stop and remove the containers, volumes and clean manually generated files. If you would like to keep any files created manually in the working directory please save them before executing this command.

## Network Variables

These are the local network variables to interact with the consensus and mirror node.

- Consensus Node Endpoint

- `127.0.0.1:50211`
- The IP address and port of the local consensus node.
> **_NOTE:_** To connect to the local consensus node from a browser you will have to use the Envoy proxy at `http://127.0.0.1:50213`.

- Consensus Node Account ID
- `0.0.3`
- The node account ID to submit transactions and queries to
- Mirror Node GRPC Endpoint
- `127.0.0.1:5600`
- The mirror node network to use
- Mirror Node REST API Endpoint
- `127.0.0.1:5551`
- The endpoint to submit rest API requests to
- Account ID
- `0.0.2`
- The account ID to use to pay for transactions and queries
- Account Key
- `302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137`
- The private key to account 0.0.2 to sign transactions and queries with

## Folder set up

1. `compose-network` folder has the static files needed for starting Local network.
2. `compose-network/grafana/dashboards` folder contains the Grafana dashboard definitions in JSON format which will be automatically provisioned at startup.
3. `compose-network/grafana/datasources` folder contains the Grafana datasource definitions in YAML format which wil be automatically provisioned at startup.
4. `network-logs` folder will be created at runtime in the working directory and will have all the log files generated after starting local node.

The local node writes its ephemeral data to a `working directory` which can be set using the `--workdir` flag, and has a default value dependant on the OS of the user

| OS | Default Working Directory |
|---------|----------------------------------------------|
| MacOS | `~/Library/Application Support/hedera-local` |
| Linux | `~/.local/share/hedera-local` |
| Windows | `%USERPROFILE%\AppData\Local\hedera-local` |

## Steps to change the memory limits, properties and other configurations

The following environment variables can be changed in the `.env` file for various memory limits

1. Platform
- PLATFORM_JAVA_HEAP_MIN
- PLATFORM_JAVA_HEAP_MAX
2. Consensus node
- NETWORK_NODE_MEM_LIMIT
3. 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
4. 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

**IMPORTANT :** Ensure to do `docker compose down -v; git clean -xfd; git reset --hard` and then `docker compose up -d` for the new changes to take any effect.

✘ The keys under `network-node` (`hedera.key`, `hedera.crt` and the `keys` folder) are only intended to be used for testing with this docker based local network. These keys should not be used with any other networks.

# Grafana & Prometheus

## Accessing Prometheus

The deployed Prometheus instance may be accessed from [http://localhost:9090](http://localhost:9090) and no credentials are required.

## Accessing Grafana

The deployed Grafana instance may be accessed from [http://localhost:3000](http://localhost:3000) and the following default credentials are needed at first login:

| User Name | Password |
| --------- | -------- |
| admin | admin |

## Adding New Dashboards

Creating new dashboards may be accomplished using the Grafana visual editor; however, these dashboards will not persist after a `docker compose down -v` command
or any other command which removes the named volumes.

Dashboards may be exported as JSON definitions and placed under the `compose-network/grafana/dashboards` folder to ensure they are automatically restored after a `docker compose down -v` or equivalent operation.

Any dashboard definitions placed into the root of the `compose-network/grafana/dashboards` folder will appear under the `General` folder in the Grafana dashboard list
Placing dashboards under a subfolder will result in a new folder in the Grafana dashboard list and the dashboards will be deployed under the folder.
25 changes: 25 additions & 0 deletions FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# FAQ

**Q: Can I run the local node on a Windows machine?**\
A: Yes but you will need WSL v2 to be installed.


**Q: Can I run the local node on MacOS with an Intel CPU?**\
A: Yes but make sure that the minimum system requirements are met.

**Q: Can I stop the local node, save its state then start it again after a while?**\
A: No, currently the local node doesn't support network freezing. Once you stop it, the next start will be with a genesis state and all of your accounts/contracts/tokens will be wiped.


**Q: What should I do if this error appears on Windows?**
```
Postgres error:
/usr/local/bin/docker-entrypoint.sh: /docker-entrypoint-initdb.d/init.sh: /bin/bash: bad interpreter: No such file or directory
Solution:
```
A: You have to set a global git config then clone the local node repository again.
```
git config --global core.autocrlf input
Delete your local repository.
Clone it again.
```
192 changes: 5 additions & 187 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,50 +11,12 @@ The Hedera Local Node project allows developers to set up their own local networ

> **_NOTE:_** It's recommended to start using the CLI Tool.

- [Docker](#docker)
- [CLI Tool](#cli-tool---hashgraphhedera-local)
- [Docker Requirements](./DOCKER-REQUIREMENTS.md)
- [Docker](./DOCKER.md#docker)
- [Environment Variables](./docs/environment-variables.md)
- [Grafana & Prometheus](#grafana--prometheus)

# Requirements

- [Node.js](https://nodejs.org/) `>= v20.11.0`
- Node version check: `node -v`
- NPM `>= v10.2.4`
- NPM version check: `npm -v`
- [Docker](https://www.docker.com/) `>= v27.3.1`
- Docker version check: `docker -v`
- [Docker Compose](https://docs.docker.com/compose/) `=> v2.29.7`
- Docker Compose version check: `docker compose version`
- Minimum 16GB RAM

### Note:

- Ensure the **VirtioFS** file sharing implementation is enabled in the docker settings

**Note**: The image may look different if you are on a different version
![docker-compose-settings.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/docker-compose-settings.png)

- Ensure the following configurations are set at minimum in Docker **Settings -> Resources** and are available for use.
- **CPUs:** 6
- **Memory:** 8 GB
- **Swap:** 1 GB
- **Disk Image Size:** 64 GB

**Note**: The image may look different if you are on a different version
![settings.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/settings.png)

- Ensure the hedera-local-node folder is added to Docker File Sharing **Settings -> Resources -> File Sharing**.
- If you're using hedera-local as npm package - running 'npm root -g' should output the path you have to add under File Sharing Docker's Setting.
- If you're using hedera-local as cloned repo - running 'pwd' in the project's root should output the path you have to add under File Sharing Docker's Setting.

**Note**: The image may look different if you are on a different version
![docker-file-sharing-settings.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/docker-file-sharing-settings.png)

- Ensure the *Allow the default Docker sockets to be used (requires password)* is enabled in Docker **Settings -> Advanced**.

**Note**: The image may look different if you are on a different version
![docker-socket-setting.png](https://raw.githubusercontent.com/hashgraph/hedera-local-node/refs/heads/main/.github/docker-socket-settings.png)
- [Grafana & Prometheus](./DOCKER.md#grafana--prometheus)
- [FAQ](./FAQ.md)

# CLI Tool - @hashgraph/hedera-local

Expand Down Expand Up @@ -459,100 +421,6 @@ defaultNetwork: 'local',
},
```

---

# Docker

> **_NOTE:_** This will not create accounts on startup, nor will perform any kind of checks.

## Start Your Local Network

1. Clone the `hedera-local-node` repo

```bash
git clone https://github.com/hashgraph/hedera-local-node.git
```

2. CD to the hedera-local-node directory

```bash
cd hedera-local-node
```

For Windows users: You will need to update the file endings of `compose-network/mirror-node/init.sh` by running this in WSL:

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

3. Run `docker compose up -d` from the terminal to get the network up and running
4. Set-up your local network client by following this [tutorial](https://docs.hedera.com/guides/docs/sdks/set-up-your-local-network)

## Stop Your Local Network

1. Run `docker compose down -v; git clean -xfd; git reset --hard` to stop and remove the containers, volumes and clean manually generated files. If you would like to keep any files created manually in the working directory please save them before executing this command.

## Network Variables

These are the local network variables to interact with the consensus and mirror node.

- Consensus Node Endpoint

- `127.0.0.1:50211`
- The IP address and port of the local consensus node.
> **_NOTE:_** To connect to the local consensus node from a browser you will have to use the Envoy proxy at `http://127.0.0.1:50213`.

- Consensus Node Account ID
- `0.0.3`
- The node account ID to submit transactions and queries to
- Mirror Node GRPC Endpoint
- `127.0.0.1:5600`
- The mirror node network to use
- Mirror Node REST API Endpoint
- `127.0.0.1:5551`
- The endpoint to submit rest API requests to
- Account ID
- `0.0.2`
- The account ID to use to pay for transactions and queries
- Account Key
- `302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137`
- The private key to account 0.0.2 to sign transactions and queries with

## Folder set up

1. `compose-network` folder has the static files needed for starting Local network.
2. `compose-network/grafana/dashboards` folder contains the Grafana dashboard definitions in JSON format which will be automatically provisioned at startup.
3. `compose-network/grafana/datasources` folder contains the Grafana datasource definitions in YAML format which wil be automatically provisioned at startup.
4. `network-logs` folder will be created at runtime in the working directory and will have all the log files generated after starting local node.

The local node writes its ephemeral data to a `working directory` which can be set using the `--workdir` flag, and has a default value dependant on the OS of the user

| OS | Default Working Directory |
|---------|----------------------------------------------|
| MacOS | `~/Library/Application Support/hedera-local` |
| Linux | `~/.local/share/hedera-local` |
| Windows | `%USERPROFILE%\AppData\Local\hedera-local` |

## Steps to change the memory limits, properties and other configurations

The following environment variables can be changed in the `.env` file for various memory limits

1. Platform
- PLATFORM_JAVA_HEAP_MIN
- PLATFORM_JAVA_HEAP_MAX
2. Consensus node
- NETWORK_NODE_MEM_LIMIT
3. 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
4. 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

**IMPORTANT :** Ensure to do `docker compose down -v; git clean -xfd; git reset --hard` and then `docker compose up -d` for the new changes to take any effect.

✘ The keys under `network-node` (`hedera.key`, `hedera.crt` and the `keys` folder) are only intended to be used for testing with this docker based local network. These keys should not be used with any other networks.

# Exposed Endpoints

| Type | Endpoint |
Expand All @@ -565,57 +433,7 @@ The following environment variables can be changed in the `.env` file for variou
| Mirror Node Explorer | [http://localhost:8080](http://localhost:8080) |
| Grafana UI | [http://localhost:3000](http://localhost:3000) |
| Prometheus UI | [http://localhost:9090](http://localhost:9090) |

# Grafana & Prometheus

## Accessing Prometheus

The deployed Prometheus instance may be accessed from [http://localhost:9090](http://localhost:9090) and no credentials are required.

## Accessing Grafana

The deployed Grafana instance may be accessed from [http://localhost:3000](http://localhost:3000) and the following default credentials are needed at first login:

| User Name | Password |
| --------- | -------- |
| admin | admin |

## Adding New Dashboards

Creating new dashboards may be accomplished using the Grafana visual editor; however, these dashboards will not persist after a `docker compose down -v` command
or any other command which removes the named volumes.

Dashboards may be exported as JSON definitions and placed under the `compose-network/grafana/dashboards` folder to ensure they are automatically restored after a `docker compose down -v` or equivalent operation.

Any dashboard definitions placed into the root of the `compose-network/grafana/dashboards` folder will appear under the `General` folder in the Grafana dashboard list
Placing dashboards under a subfolder will result in a new folder in the Grafana dashboard list and the dashboards will be deployed under the folder.

# FAQ

- Can I run the local node on a Windows machine?
- Yes but you will need WSL v2 to be installed.


- Can I run the local node on MacOS with an Intel CPU?
- Yes but make sure that the minimum system requirements are met.


- Can I stop the local node, save its state then start it again after a while?
- No, currently the local node doesn't support network freezing. Once you stop it, the next start will be with a genesis state and all of your accounts/contracts/tokens will be wiped.


- What should I do if this error appears on Windows?
```
Postgres error:
/usr/local/bin/docker-entrypoint.sh: /docker-entrypoint-initdb.d/init.sh: /bin/bash: bad interpreter: No such file or directory
Solution:
```
- You have to set a global git config then clone the local node repository again.
```
git config --global core.autocrlf input
Delete your local repository.
Clone it again.
```
---

# Support

Expand Down
Loading