[UX/UI] As a User, I want to have a easy to ready and follow docs, so I can run Mina Node/Demos effortlessly

[lukasimrich]

WHAT
Readme docs and Producer Demo docs

WHY
I went through these docs a few times as a user, and had some ideas to improve structure so it prioritizes macOS and it is easier to follow

HOW

• First, I condensed the start and added TOC, TOC is a nice touch to showcase what is actually inside and we have two slightly distinct categories: (1)Trying stuff, (2)Exploring and Understanding Code

• Second, I added some context to block producer section, so it is more obvious what to expect in the detailed guide

• Third, I restructured and Renamed Titles around building a node, I wanted headlines to be as informative as it gets - So I replaced generic how to launch with/without docker compose with more specific titles

  • Quick-start a Node with Docker Compose
  • Building a Node from Source
  • I made the UI section part of Building a Node from source, so it nicely flows. Although, I am aware its rather an optional step, so do I believe anyone who is buildint a node from source code understands that dashboard is just an extra step

[lukasimrich]

The OpenMina Node

The OpenMina Node is a Mina node written entirely in Rust, capable of verifying blocks of transactions, producing blocks and generating SNARKs.

Unlike the resource-limited Mina Web Node, OpenMina handles resource-intensive tasks like SNARK proof generation.

The OpenMina node allows you to	In Development	Future Plans
☑ Connect to the network and sync up to the best tip block	☐ Produce SNARKs in Rust (currently we use OCaml subprocess for that)	☐ Direct transfer of MINA funds
☑ Validate and apply new blocks and transactions to update consensus and ledger state		☐ Block production
☑ Produce SNARKs to complete SNARK work		☐ The ability to record/replay all blocks
☑ Broadcast messages: blocks, SNARK pool		☐ SnarkyJS support for Rust node, enabling direct injection of simple transactions, such as transferring Mina funds
☑ SNARK proof generation for transactions

Table of Contents

• Try Yourself
  • Block Producer Demo
  • Quick-start a Node with Docker Compose
  • Building a Node from Source
• Learn about the Repository
  • Repository Structure
  • Documentation
  • License

Block Producer Demo

This demo runs in a private network with block proofs disabled, eliminating the need to wait for staking ledger inclusion.

Follow the detailed guide.

Quick-start a Node with Docker Compose

1. Run:

docker compose up

2. Visit http://localhost:8070 in your browser.

• By default, docker compose up will use the latest node and frontend images available (tagged with latest), but specific versions can be selected by using the OPENMINA_TAG and OPENMINA_FRONTEND_TAG variables.
• The node will be running on the Berkeley network.

Building a Node from Source

This installation guide has been tested on Debian and Ubuntu and should work on most distributions of Linux.

1. Install node pre-requisites:

Ubuntu or Debian-based Linux distribution with the following packages installed:

• curl
• git
• libssl-dev
• pkg-config
• protobuf-compiler
• build-essential

MacOS

If Homebrew is not installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install curl git openssl pkg-config protobuf gcc make

Linux (Debian-based)

# Either using "sudo" or as the "root" user
sudo apt install curl git libssl-dev pkg-config protobuf-compiler build-essential

2. Build and Run the Node:

Steps (for Debian-based Linux distros and macOS):

Open up the command line and enter the following:

# Install rustup and set the default Rust toolchain to 1.77 (newer versions work too)
curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain 1.77
# Setup the current shell with rustup
source "$HOME/.cargo/env"
# Clone the openmina repository
git clone https://github.com/openmina/openmina.git
cd openmina/
# Build and run the node
cargo run --release -p cli node

3. Install Dashboard pre-requisites:

3A. Node.js v20.11.1

MacOS

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install [email protected]

Linux (Debian-based)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
source ~/.bashrc
nvm install 20.11.1

Windows

Download Node.js v20.11.1 from the official website, open the installer and follow the prompts to complete the installation.

3B. Angular CLI v16.2.0

npm install -g @angular/[email protected]

4. Build and Run Dashboard Application

4A. Open a terminal and navigate to this project's root directory:

cd PROJECT_LOCATION/openmina/frontend

4B. Install the dependencies:

npm install

4C. Run the application:

npm start

Repository Structure

• core/ - Provides basic types needed to be shared across different
  components of the node.
• ledger/ - Mina ledger implementation in Rust.
• snark/ - Snark/Proof verification.
• p2p/ - P2p implementation for OpenMina node.
• node/ - Combines all the business logic of the node.
  • native/ - OS specific pieces of the node, which is
    used to run the node natively (Linux/Mac/Windows).
  • testing/ - Testing framework for OpenMina node.
• cli/ - OpenMina cli.
• frontend/ - OpenMina frontend.

Details regarding architecture

The Open Mina Documentation

• Why we are developing Open Mina
• What is Open Mina?
  • Openmina Node
  • The Mina Web Node
• Core components
  • P2P communication
    • GossipSub
  • Scan state
  • SNARKs
• Developer tools
  • Debugger
  • Front End
    • Dashboard
• Testing
• How to run
  • Launch Openmina node
  • Launch Node with UI
  • Debugger
  • Web Node
• External links
  • Medium
  • Twitter

---

Block Producer Demo

This demo runs in a private network with block proofs disabled, eliminating the need to wait for staking ledger inclusion.

Follow the detailed guide.

Quick-start a Node with Docker Compose

1. Run:

docker compose up

2. Visit http://localhost:8070 in your browser.

• By default, docker compose up will use the latest node and frontend images available (tagged with latest), but specific versions can be selected by using the OPENMINA_TAG and OPENMINA_FRONTEND_TAG variables.
• The node will be running on the Berkeley network.

Building a Node from Source

This installation guide has been tested on Debian and Ubuntu and should work on most distributions of Linux.

1. Install node pre-requisites:

Ubuntu or Debian-based Linux distribution with the following packages installed:

• curl
• git
• libssl-dev
• pkg-config
• protobuf-compiler
• build-essential

MacOS

If Homebrew is not installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install curl git openssl pkg-config protobuf gcc make

Linux (Debian-based)

# Either using "sudo" or as the "root" user
sudo apt install curl git libssl-dev pkg-config protobuf-compiler build-essential

2. Build and Run the Node:

Steps (for Debian-based Linux distros and macOS):

Open up the command line and enter the following:

# Install rustup and set the default Rust toolchain to 1.77 (newer versions work too)
curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain 1.77
# Setup the current shell with rustup
source "$HOME/.cargo/env"
# Clone the openmina repository
git clone https://github.com/openmina/openmina.git
cd openmina/
# Build and run the node
cargo run --release -p cli node

3. Install Dashboard pre-requisites:

3A. Node.js v20.11.1

MacOS

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install [email protected]

Linux (Debian-based)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
source ~/.bashrc
nvm install 20.11.1

Windows

Download Node.js v20.11.1 from the official website, open the installer and follow the prompts to complete the installation.

3B. Angular CLI v16.2.0

npm install -g @angular/[email protected]

4. Build and Run Dashboard Application

4A. Open a terminal and navigate to this project's root directory:

cd PROJECT_LOCATION/openmina/frontend

4B. Install the dependencies:

npm install

4C. Run the application:

npm start

Repository Structure

• core/ - Provides basic types needed to be shared across different
  components of the node.
• ledger/ - Mina ledger implementation in Rust.
• snark/ - Snark/Proof verification.
• p2p/ - P2p implementation for OpenMina node.
• node/ - Combines all the business logic of the node.
  • native/ - OS specific pieces of the node, which is
    used to run the node natively (Linux/Mac/Windows).
  • testing/ - Testing framework for OpenMina node.
• cli/ - OpenMina cli.
• frontend/ - OpenMina frontend.

Details regarding architecture

The Open Mina Documentation

• Why we are developing Open Mina
• What is Open Mina?
  • Openmina Node
  • The Mina Web Node
• Core components
  • P2P communication
    • GossipSub
  • Scan state
  • SNARKs
• Developer tools
  • Debugger
  • Front End
    • Dashboard
• Testing
• How to run
  • Launch Openmina node
  • Launch Node with UI
  • Debugger
  • Web Node
• External links
  • Medium
  • Twitter

Producer Demo Launch Guide with Docker

This demo showcases the block production capabilities of OpenMina nodes within a private network. It launches three OpenMina nodes on your local machine, operating in a private network environment. For the purpose of this demonstration, block proofs are disabled. This setup allows you to observe block production immediately, without the need to wait for your account to be included in the staking ledger on testnets.

Table of Contents

1. Prerequisite - Docker Installation
   • macOS
   • Linux (Debian-based)
   • Windows
2. Running the Producer Demo
   • macOS
   • Linux (Debian-based)
   • Windows

Prerequisite - Docker Installation

macOS

1. Download Docker Desktop for Mac from the Docker Website.

2. Open the downloaded .dmg file and drag Docker to the Applications folder.

3. Open Docker from the Applications folder and follow the installation steps.

4. Open up a terminal window by using the shortcut Command + Space and type in terminal

5. Verify the installation by running the following command in your terminal:

   docker --version

Linux (Debian-based)

1. Set up Docker's apt repository:

   # Add Docker's official GPG key:
   sudo apt-get update
   sudo apt-get install ca-certificates curl
   sudo install -m 0755 -d /etc/apt/keyrings
   sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
   sudo chmod a+r /etc/apt/keyrings/docker.asc
   
   # Add the repository to Apt sources:
   echo \
   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update

2. Install the Docker packages:

   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. Add your user to the docker group:

   sudo usermod -aG docker $USER
   newgrp docker

4. Verify the installation:

   docker run hello-world

Windows

1. Download Docker Desktop for Windows from the Docker Website.

2. Run the installer and follow the instructions.

3. After installation, Docker will start automatically. Verify that Docker Desktop is running by checking the Docker icon in your system tray.

Running the Producer Demo

macOS

1. Open a terminal by pressing command + space on your keyboard and type in terminal

2. Clone this repository:

   git clone https://github.com/openmina/openmina.git

3. Navigate to the repository:

   cd openmina

4. Run the following command to start the demo:

   docker compose -f docker-compose.local.producers.yml up

5. Open you browser and visit http://localhost:8070

Linux (Debian-based)

1. Clone this repository:

   git clone https://github.com/openmina/openmina.git

2. Navigate to the repository:

   cd openmina

3. Run the following command to start the demo:

   docker compose -f docker-compose.local.producers.yml up

4. Open you browser and visit http://localhost:8070

Windows

1. Open the command prompt by pressing the windows button on your keyboard and type in command prompt

2. Clone this repository:

   git clone https://github.com/openmina/openmina.git

3. Navigate to the repository:

   cd openmina

4. Run the following command to start the demo:

   docker compose -f docker-compose.local.producers.yml up

5. Open you browser and visit http://localhost:8070