Skip to content

docs: unify node runner documentation with makefile targets #1283

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

Merged
merged 1 commit into from
Aug 13, 2025
Merged

docs: unify node runner documentation with makefile targets #1283

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
8 changes: 7 additions & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ OPENMINA_LIBP2P_PORT ?= 8302

# Utilities
NETWORK ?= devnet
VERBOSITY ?= info
GIT_COMMIT := $(shell git rev-parse --short=8 HEAD)

.PHONY: help
Expand All @@ -38,7 +39,7 @@ build-ledger: download-circuits ## Build the ledger binary and library, requires

.PHONY: build-release
build-release: ## Build the project in release mode
cargo build --release --package=cli --bin openmina
@cargo build --release --package=cli --bin openmina

.PHONY: build-testing
build-testing: ## Build the testing binary with scenario generators
Expand Down Expand Up @@ -294,6 +295,11 @@ docker-build-test: ## Build test Docker image
docker build -t $(DOCKER_ORG)/openmina-test:$(GIT_COMMIT) \
-f node/testing/docker/Dockerfile.test node/testing/docker/

# Node running targets
.PHONY: run-node
run-node: build-release ## Run a basic node (NETWORK=devnet, VERBOSITY=info)
@cargo run --release --package=cli --bin openmina -- node --network $(NETWORK) --verbosity $(VERBOSITY)

# Postgres related targets + archive node
.PHONY: run-archive
run-archive: build-release ## Run an archive node with local storage
Expand Down
116 changes: 107 additions & 9 deletions cli/src/commands/node/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,41 @@ use node::{

use openmina_node_native::{archive::config::ArchiveStorageOptions, tracing, NodeBuilder};

/// Openmina node
/// OpenMina node configuration and runtime options
///
/// This struct defines all available command-line parameters for running an OpenMina node.
/// The node can operate in different modes (basic node, block producer, archive node)
/// depending on the parameters provided.
///
/// # Basic Usage
///
/// ```bash
/// # Run a basic node on devnet
/// openmina node --network devnet
///
/// # Run with custom ports and logging
/// openmina node --network devnet --port 3001 --libp2p-port 8303 --verbosity debug
/// ```
///
/// # Block Producer Mode
///
/// ```bash
/// # Run as block producer
/// openmina node --network devnet --producer-key /path/to/key --coinbase-receiver B62q...
/// ```
///
/// # Archive Node Mode
///
/// ```bash
/// # Run as archive node with local storage
/// openmina node --network devnet --archive-local-storage
/// ```
#[derive(Debug, clap::Args)]
pub struct Node {
/// Working directory for node data, logs, and configuration files
///
/// Can be set via OPENMINA_HOME environment variable.
/// Defaults to ~/.openmina
#[arg(
long,
short = 'd',
Expand All @@ -31,7 +63,10 @@ pub struct Node {
)]
pub work_dir: String,

/// Peer secret key
/// P2P networking secret key for node identity
///
/// If not provided, a new key will be generated automatically.
/// Can be set via OPENMINA_P2P_SEC_KEY environment variable.
#[arg(long, short = 's', env = "OPENMINA_P2P_SEC_KEY")]
pub p2p_secret_key: Option<SecretKey>,

Expand All @@ -49,15 +84,28 @@ pub struct Node {
#[arg(long)]
pub libp2p_external_ip: Vec<String>,

/// Http port to listen on
/// HTTP server port for RPC API and web interface
///
/// The node will serve its HTTP API and dashboard on this port.
/// Default: 3000
#[arg(long, short, env, default_value = "3000")]
pub port: u16,

/// LibP2P port to listen on
/// LibP2P networking port for peer-to-peer communication
///
/// This port is used for connecting to other nodes in the network.
/// Default: 8302
#[arg(long, env, default_value = "8302")]
pub libp2p_port: u16,

/// Verbosity level (options: trace, debug, info, warn, error)
/// Logging verbosity level
///
/// Controls the amount of logging output. Options in order of verbosity:
/// - error: Only show errors
/// - warn: Show warnings and errors
/// - info: Show informational messages, warnings, and errors (default)
/// - debug: Show debug information and all above
/// - trace: Show all possible logging output
#[arg(long, short, env, default_value = "info")]
pub verbosity: Level,

Expand All @@ -73,21 +121,71 @@ pub struct Node {
#[arg(long, env = "OPENMINA_LOG_PATH", default_value = "$OPENMINA_HOME")]
pub log_path: String,

/// Initial peers to connect to on startup
///
/// Specify peer multiaddresses to connect to when the node starts.
/// Can be used multiple times to add multiple peers.
///
/// # Multiaddr Format
///
/// Multiaddresses follow the format: `/protocol/address/protocol/port/protocol/peer_id`
///
/// **IPv4 Example:**
/// ```
/// /ip4/192.168.1.100/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
/// ```
///
/// **IPv6 Example:**
/// ```
/// /ip6/2001:db8::1/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
/// ```
///
/// **DNS Example:**
/// ```
/// /dns4/node.example.com/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
/// ```
///
/// Where:
/// - `ip4/ip6/dns4` specifies the address type
/// - IP address or hostname
/// - `tcp` protocol with port number (typically 8302 for OpenMina)
/// - `p2p` protocol with the peer's public key identifier
#[arg(long, short = 'P', alias = "peer")]
pub peers: Vec<P2pConnectionOutgoingInitOpts>,

/// File containing initial peers.
/// File containing initial peers to connect to
///
/// Each line should contain peer's multiaddr.
/// Each line should contain a peer's multiaddr following the format described above.
///
/// **Example file content:**
/// ```
/// /ip4/192.168.1.100/tcp/8302/p2p/12D3KooWABCDEF1234567890abcdef...
/// /ip4/10.0.0.50/tcp/8302/p2p/12D3KooWXYZ9876543210fedcba...
/// /dns4/bootstrap.example.com/tcp/8302/p2p/12D3KooW123ABC...
/// ```
///
/// Empty lines and lines starting with `#` are ignored.
#[arg(long, env)]
pub peer_list_file: Option<PathBuf>,

/// File containing initial peers.
/// URL to fetch initial peers list from
///
/// Each line should contain peer's multiaddr.
/// The URL should return a text file with one peer multiaddr per line,
/// using the same format as described in `peer_list_file`.
/// Useful for dynamic peer discovery from a central bootstrap service.
///
/// **Example URL response:**
/// ```
/// /ip4/bootstrap1.example.com/tcp/8302/p2p/12D3KooW...
/// /ip4/bootstrap2.example.com/tcp/8302/p2p/12D3KooX...
/// ```
#[arg(long, env)]
pub peer_list_url: Option<Url>,

/// Maximum number of peer connections to maintain
///
/// The node will attempt to maintain up to this many connections
/// to other peers in the network. Default: 100
#[arg(long, default_value = "100")]
pub max_peers: usize,

Expand Down
126 changes: 50 additions & 76 deletions website/docs/node-runners/building-from-source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,104 +1,78 @@
# How to build and launch a node from source

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

## Prerequisites
For detailed instructions on how to build OpenMina from source, including system
dependencies, toolchain setup, and platform-specific instructions, please refer
to the [Getting Started for Developers](../developers/getting-started.mdx)
guide.

Ubuntu or Debian-based Linux distribution with the following packages installed:
The developer guide includes:

- `curl`
- `git`
- `libssl-dev`
- `pkg-config`
- `protobuf-compiler`
- `build-essential`
- Tested setup instructions for Ubuntu 22.04, Ubuntu 24.04, and macOS
- Complete toolchain installation (Rust, Node.js, Docker, etc.)
- Build verification and testing procedures
- Environment configuration

Example (debian-based):
## Running the Node

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

Example (macOS):

If you have not yet installed homebrew:
Once you have built OpenMina following the developer guide, you can run the node
using the provided Makefile targets:

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

```sh
brew install curl git openssl pkg-config protobuf gcc make
```
### Available Make Targets

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

Open up the command line and enter the following:

And then:
```bash
# Run a basic node (defaults: NETWORK=devnet, VERBOSITY=info)
make run-node

```sh
# Install rustup and set the default Rust toolchain to 1.84 (newer versions work too)
curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain 1.84
# 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
# Run with custom network and verbosity level
make run-node NETWORK=mainnet VERBOSITY=debug
```

# How to launch the UI:

## Prerequisites

### 1. Node.js v20.11.1

#### MacOS
#### Archive Node

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

#### Linux
# Run an archive node with local storage
make run-archive

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
source ~/.bashrc
nvm install 20.11.1
# Run archive node on mainnet
make run-archive NETWORK=mainnet
```

#### Windows
For comprehensive archive node setup including different storage options,
database configuration, and Docker Compose deployment, see the detailed
[Archive Node](./archive-node.md) documentation.

Download [Node.js v20.11.1](https://nodejs.org/) from the official website, open
the installer and follow the prompts to complete the installation.
### Configuration Variables

### 2. Angular CLI v16.2.0
The Makefile supports the following configuration variables that can be
overridden:

```bash
npm install -g @angular/[email protected]
```
- `NETWORK` - Network to connect to (default: `devnet`, options: `devnet`,
`mainnet`)
- `VERBOSITY` - Logging verbosity level (default: `info`, options: `error`,
`warn`, `info`, `debug`, `trace`)

### 3. Installation
### Advanced Configuration and CLI Parameters

Open a terminal and navigate to this project's root directory
For detailed information about all available command-line parameters and
advanced configuration options, please refer to the
[Rust API Documentation](https://o1-labs.github.io/openmina/api-docs/cli/commands/node/struct.Node.html)
which contains comprehensive documentation for all supported parameters
including:

```bash
cd PROJECT_LOCATION/openmina/frontend
```

Install the dependencies

```bash
npm install
```
- Network and connection options
- Block producer configuration
- Archive node settings
- Logging and debugging options
- P2P networking parameters
- Snarker configuration
- And more

## Run the application
You can also get help directly from the command line:

```bash
npm start
./target/release/openmina node --help
```
Loading