Skip to main content

​
Overview

Building Ubu-Block from source gives you the flexibility to customize the platform and stay up-to-date with the latest development changes. This guide walks you through the entire build process.
If you prefer to use pre-built binaries, download them from the releases page and skip to the Configuration guide.

​
Prerequisites

Before building, ensure you have:
  • Met all system requirements
  • Installed the Rust toolchain (edition 2024)
  • Installed required system libraries
  • Git installed for cloning the repository

​
Cloning the Repository

1

Clone the repository

Clone the Ubu-Block repository from GitHub:
git clone https://github.com/ubu-block/ubu-block.git
cd ubu-block
2

Verify the workspace structure

Ubu-Block uses a Cargo workspace with multiple members:
ls -la
You should see:
  • apps/ - CLI, API, and web applications
  • nodes/ - Observer, submission, and verification node implementations
  • crates/ - Core libraries (blockchain, database, types)
  • Cargo.toml - Workspace configuration

​
Building the Project

​
Full Workspace Build

1

Build all workspace members

Build the entire workspace including all nodes and applications:
cargo build --release
The --release flag enables optimizations. Build time may take 5-15 minutes depending on your hardware.
The compiled binaries will be located in target/release/.
2

Verify the build

Check that the build completed successfully:
ls target/release/
You should see executables for:
  • ubu-block (CLI)
  • observer (Observer node)
  • submission (Submission node)
  • Other workspace binaries

​
Building Specific Components

You can build individual components instead of the entire workspace: 
cargo build --release -p ubu-block
The CLI tool provides commands for initializing, validating, and querying the blockchain.

​
Development Builds

For development and testing, you can use unoptimized builds: 
cargo build
Development builds:
  • Compile much faster (1-3 minutes)
  • Include debug symbols
  • Have reduced performance
  • Are located in target/debug/
Never use development builds in production. They lack critical optimizations and security hardening.

​
Testing the Build

1

Run the test suite

Execute all tests to verify the build:
cargo test
This runs unit tests for all workspace members.
2

Test the CLI

Verify the CLI application works:
cargo run --release -p ubu-block -- --help
You should see the help output with available commands.

​
Installing System-Wide

Optionally, install the binaries to your system path: 
cargo install --path apps/cli
cargo install --path nodes/observer
cargo install --path nodes/submission
After installation, you can run commands directly: 
ubu-block --help
observer --config config.toml
submission --config config.toml

​
Build Troubleshooting

If you encounter OpenSSL-related errors:On Ubuntu/Debian:
sudo apt install pkg-config libssl-dev
On macOS:
brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)
On Windows: Consider using the rustls feature instead of OpenSSL.
If SQLite fails to link:On Ubuntu/Debian:
sudo apt install libsqlite3-dev
On macOS:
brew install sqlite
If the build runs out of memory:
  • Use cargo build --release -j 1 to limit parallel jobs
  • Close other applications to free memory
  • Add swap space if running on a low-memory system
If you see errors about edition 2024:
rustup update stable
rustc --version  # Should be 1.85.0 or later
Edition 2024 requires Rust 1.85+. Update your toolchain if needed.

​
Build Configuration

​
Optimizing Build Performance

Speed up compilation with these optional configurations in ~/.cargo/config.toml: 
[build]
jobs = 4  # Adjust based on your CPU cores

[profile.dev]
opt-level = 1  # Slight optimization for dev builds

[profile.release]
lto = "thin"  # Link-time optimization
codegen-units = 1  # Better optimization, slower build

​
Cross-Compilation

To build for a different target architecture: 
# Install the target
rustup target add x86_64-unknown-linux-gnu

# Build for target
cargo build --release --target x86_64-unknown-linux-gnu

​
Updating the Build

To update to the latest version:
1

Pull the latest changes

git pull origin main
2

Clean previous builds

cargo clean
3

Rebuild

cargo build --release

​
Next Steps

Configuration

Configure your node after building

Running Nodes

Learn how to run different node types

Build docs developers (and LLMs) love

Get started for freeTalk to us