Besu Dev Quickstart

Table of Contents

1. Prerequisites
2. Usage
3. Troubleshooting
4. Publishing

Prerequisites

To run these tutorials, you must have the following installed:

• Docker and Docker-compose v2 or higher

⚠️ Note: If on MacOS or Windows, please ensure that you allow docker to use upto 4G of memory or 6G if running the Private network setup, and approx twice that amount for the public network setup. The Docker for Mac and Docker Desktop sites have details on how to allocate system resources

⚠️ Note: This has only been tested on Windows 11 25H2, WSL2 and Docker

• On Windows, please use WSL2 kernels 6.6x or higher
• You can use either Docker Desktop or docker-engine (with the compose plugin) within the WSL2 environment
• Nodejs or Yarn

Usage

Create the docker compose file and artifacts with the command below.

$> npx @consensys/besu-dev-quickstart
         ____                                         
        / __ )___  _______  __                        
       / __  / _ \/ ___/ / / /                        
      / /_/ /  __(__  ) /_/ /                         
     /_____/\___/____/\__,_/  __                      
        / __ \___ _   _____  / /___  ____  ___  _____ 
       / / / / _ \ | / / _ \/ / __ \/ __ \/ _ \/ ___/ 
      / /_/ /  __/ |/ /  __/ / /_/ / /_/ /  __/ /     
     /_____/\___/|___/\___/_/\____/ .___/\___/_/      
       ____        _      __     /_/__             __ 
      / __ \__  __(_)____/ /_______/ /_____ ______/ /_
     / / / / / / / / ___/ //_/ ___/ __/ __ / ___/ __/
    / /_/ / /_/ / / /__/ ,< (__  ) /_/ /_/ / /  / /_  
    \___\_\__,_/_/\___/_/|_/____/\__/\__,_/_/   \__/         


Welcome to the Besu Developer Quickstart utility. This tool can be used
to rapidly generate a local public node or private network for development purposes.

To get started, be sure that you have both Docker and Docker Compose
installed, then answer the following questions.

What type of network would you like the client to run? Default: [1]
    1. Private
    2. Public

Add Otel Collector spans to Grafana? Default: [N/y]
 
Do you wish to enable the Chainlens explorer? Default: [N/y]
 
Where should we create the config files for this network? Please
choose either an empty directory, or a path to a new directory that does
not yet exist. Default: ./besu-test-network

Once completed, change directory to the artifacts folder: 

```bash
$> cd besu-test-network
besu-test-network $> ./run.sh

Alternatively, you can use cli options and skip the prompt above like so:

npx @consensys/besu-dev-quickstart --networkType private --outputPath ./besu-test-network --otel false --chainlens false

Troubleshooting

Besu only - java.io.IOException: Permission denied for volumes

The besu containers use user besu mapped to user:group 1000. On your local machine, if your userid is not 1000, you will see this error. To fix this either run as user 1000 or map the container's user 1000 to your local user id so permissions will work like so in the compose file

image: some:img
user: $(id -u):$(id -g)

Deleting the 'data' folder for volumes

Containers run as the default users and we do not alter them. If you run into issues deleting the data folder, you will need to use sudo permissions to do that.

Publishing

The package is published to npm as @consensys/besu-dev-quickstart with public access. You need publish rights in the @consensys npm org.

1. Bump the version in a pull request. This updates package.json and npm-shrinkwrap.json without committing or tagging:

   npm version minor --no-git-tag-version   # or patch / major

   Merge the pull request once it's approved.

2. Start from an up-to-date master with no uncommitted changes, and check you're logged in to npm:

   git checkout master && git pull
   npm whoami          # run `npm login` if this fails

3. Check what will be published:

   npm run release:dry-run

4. Build, lint and publish:

   npm run release

   This runs clear, build and lint, then publishes with the latest tag. If this version is already on npm, the publish is skipped.

5. Once the publish succeeds, tag the release and push the tag:

   git tag X.Y.Z && git push origin X.Y.Z

If step 4 fails partway, fix the problem and run npm run release again. Any name that already has this version on npm is skipped.