diff --git a/Makefile b/Makefile index 6f8cb6d1d6..7329b60cf1 100644 --- a/Makefile +++ b/Makefile @@ -22,6 +22,7 @@ OPENMINA_LIBP2P_PORT ?= 8302 # Utilities NETWORK ?= devnet +VERBOSITY ?= info GIT_COMMIT := $(shell git rev-parse --short=8 HEAD) .PHONY: help @@ -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 @@ -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 diff --git a/cli/src/commands/node/mod.rs b/cli/src/commands/node/mod.rs index ec1bab8658..c240ef825a 100644 --- a/cli/src/commands/node/mod.rs +++ b/cli/src/commands/node/mod.rs @@ -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', @@ -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, @@ -49,15 +84,28 @@ pub struct Node { #[arg(long)] pub libp2p_external_ip: Vec, - /// 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, @@ -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, - /// 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, - /// 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, + /// 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, diff --git a/website/docs/node-runners/building-from-source.md b/website/docs/node-runners/building-from-source.md index 1df3192eb1..5efb9c0716 100644 --- a/website/docs/node-runners/building-from-source.md +++ b/website/docs/node-runners/building-from-source.md @@ -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 node@20.11.1 -``` - -#### 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/cli@16.2.0 -``` +- `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 ```