Skip to main content
You can install Ubu-Block either by building from source or downloading pre-built binaries. Building from source gives you the latest features, while binaries are faster to set up.

​
System requirements

Ubu-Block runs on Linux, macOS, and Windows with minimal requirements:
  • CPU: Any modern 64-bit processor
  • RAM: 2GB minimum (4GB recommended for Verification nodes)
  • Storage: 500MB for the application, plus space for blockchain data
  • Network: Stable internet connection for P2P communication

​
Install from pre-built binaries

The fastest way to get started is with pre-built binaries from the releases page.
1

Download the binary

Visit the GitHub releases page and download the latest binary for your platform:
# Download and extract (replace VERSION with actual version)
wget https://github.com/koleshjr/ubu-block/releases/download/VERSION/ubu-block-x86_64-unknown-linux-gnu.tar.gz
tar -xzf ubu-block-x86_64-unknown-linux-gnu.tar.gz
2

Move to system path (optional)

For easier access, move the binary to a directory in your PATH:
sudo mv ubu-block /usr/local/bin/
chmod +x /usr/local/bin/ubu-block
3

Download required files

Get the SQL setup files needed for initialization:
# Create data directory
mkdir data

# Download empty database template
wget https://raw.githubusercontent.com/koleshjr/ubu-block/main/crates/database/sql/empty.db

# Copy to both database locations
cp empty.db data/blockchain.db
cp empty.db data/private.db

# Download initialization SQL
wget https://raw.githubusercontent.com/koleshjr/ubu-block/main/apps/cli/init.sql
4

Create configuration file

Create a config.toml file with your database paths:
config.toml
main_db = "sqlite://data/blockchain.db"
private_db = "sqlite://data/private.db"
5

Verify installation

Test that the binary works:
ubu-block --version
You should see the version number printed.
When using binaries, replace cargo run --bin ubu-block-cli -- with just ubu-block in all commands.

​
Build from source

Building from source gives you access to the latest features and allows you to contribute to development.

​
Install Rust

If you don’t have Rust installed: 
# Install rustup (Rust toolchain installer)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the prompts, then reload your shell
source $HOME/.cargo/env
Verify the installation: 
rustc --version
cargo --version
You need Rust 1.70 or later.

​
Clone and build

1

Clone the repository

git clone https://github.com/koleshjr/ubu-block
cd ubu-block
2

Build the project

Build all workspace members in release mode:
cargo build --release
This compiles the CLI, API server, and all node types. The first build takes 5-10 minutes as Cargo downloads and compiles dependencies.
The --release flag enables optimizations. Development builds are faster to compile but slower to run.
3

Set up the database

Create the data directory and copy database templates:
mkdir data
cp crates/database/sql/empty.db data/blockchain.db
cp crates/database/sql/empty.db data/private.db
4

Verify the build

Run the CLI to check that everything works:
cargo run --bin ubu-block-cli -- --help
You should see the help text with available commands.

​
Build specific components

Ubu-Block uses a Cargo workspace with multiple apps and crates. You can build individual components: 
cargo build --release --bin ubu-block-cli
# Binary: target/release/ubu-block-cli

​
Configuration

Both installation methods require a config.toml file. Create it in your working directory:
config.toml
# Path to the main blockchain database
main_db = "sqlite://data/blockchain.db"

# Path to the private key database
private_db = "sqlite://data/private.db"
Keep private.db secure! It contains your node’s cryptographic keys. Never commit it to version control or share it publicly.

​
Advanced configuration

For node operations, you can add additional settings:
config.toml
main_db = "sqlite://data/blockchain.db"
private_db = "sqlite://data/private.db"

# P2P networking
[p2p]
listen_addr = "0.0.0.0:9000"
bootstrap_nodes = [
  "/ip4/157.230.xxx.xxx/tcp/9000/p2p/12D3KooWxxxxx"
]

# API server (for Submission/Observer nodes)
[api]
bind_addr = "0.0.0.0:8080"
cors_origins = ["*"]

​
Update Ubu-Block

​
Update binary installation

  1. Download the latest release from GitHub
  2. Replace your existing binary
  3. Restart any running nodes

​
Update source installation

cd ubu-block
git pull origin main
cargo build --release
Your blockchain data in data/ persists across updates. Database migrations are handled automatically if needed.

​
Troubleshooting

​
Build errors

“linker ‘cc’ not found” (Linux) 
# Ubuntu/Debian
sudo apt install build-essential

# Fedora/RHEL
sudo dnf install gcc
OpenSSL errors (Linux) 
# Ubuntu/Debian
sudo apt install pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install pkgconfig openssl-devel
SQLite errors 
# Ubuntu/Debian
sudo apt install libsqlite3-dev

# Fedora/RHEL
sudo dnf install sqlite-devel

​
Runtime errors

“Failed to read config file” Make sure config.toml exists in your current directory or provide the path explicitly: 
cargo run --bin ubu-block-cli -- -c /path/to/config.toml <command>
“Failed to connect to database” Verify that your database files exist: 
ls -l data/
# Should show blockchain.db and private.db
“Failed to parse config file” Check that your config.toml has valid TOML syntax. Common issues:
  • Missing quotes around strings
  • Incorrect path separators on Windows (use forward slashes or escaped backslashes)

​
Next steps

Quickstart guide

Initialize your first blockchain and submit results

Configuration

Learn about all configuration options

Run a node

Set up Observer, Submission, or Verification nodes

CLI reference

Explore all available CLI commands

Build docs developers (and LLMs) love

Get started for freeTalk to us