Skip to main content

​
Overview

Ubu-Block uses TOML configuration files to manage node settings, database connections, network addresses, and peer configurations. This guide covers all configuration options for different node types.

​
Configuration File Structure

Configuration files use the TOML format and are passed to nodes via the --config flag: 
submission --config config.toml

​
Basic Configuration

A minimal configuration file includes:
config.toml
main_db = "sqlite://./data/blockchain.db"
private_db = "sqlite://./data/private.db"

​
Database Configuration

​
Database Paths

Ubu-Block requires two SQLite databases: 
main_db = "sqlite://./data/blockchain.db"
private_db = "sqlite://./data/private.db"
In-memory databases are only suitable for testing. All data is lost when the node stops.

​
Database Files

DatabasePurposeAccessibility
blockchain.dbStores blocks, transactions, election results, and public blockchain dataPublic, read-only for queries
private.dbStores private keys, node identity, and sensitive configurationPrivate, restricted access

​
Network Configuration

​
Submission Node Configuration

Submission nodes require both P2P and HTTP API addresses:
config.toml
main_db = "sqlite://./data/blockchain.db"
private_db = "sqlite://./data/private.db"
http_addr = "127.0.0.1:9091"
node_addr = "127.0.0.1:9090"
Configuration Options:
  • http_addr: HTTP API server address (default: 127.0.0.1:9091)
  • node_addr: P2P network address (default: 127.0.0.1:9090)
For production deployments, bind to 0.0.0.0 instead of 127.0.0.1 to accept external connections.

​
Observer Node Configuration

Observer nodes only need database paths and a peer to connect to:
config.toml
main_db = "sqlite://./data/blockchain.db"
private_db = "sqlite://./data/private.db"
The peer address is typically hardcoded or passed as a command-line argument: 
observer --peer 127.0.0.1:9090

​
Multiple Node Configuration

When running multiple nodes on the same machine, use different ports and database paths: 
main_db = "sqlite://./data/blockchain.db"
private_db = "sqlite://./data/private.db"
http_addr = "127.0.0.1:9091"
node_addr = "127.0.0.1:9090"

​
Peer Configuration

Ubu-Block supports P2P networking for node synchronization.

​
Connecting to Peers

Peers can be configured in the TOML file:
config.toml
main_db = "sqlite://./data/blockchain.db"
private_db = "sqlite://./data/private.db"
http_addr = "127.0.0.1:9091"
node_addr = "127.0.0.1:9090"

[[peers]]
name = "peer1"
address = "157.230.123.45:9090"

[[peers]]
name = "peer2"
address = "192.168.1.100:9090"

​
P2P Configuration Options

Advanced P2P settings can be configured:
config.toml
[peer_config]
max_connections = 50
connection_timeout = 30
heartbeat_interval = 10
Options:
  • max_connections: Maximum number of peer connections (default: 50)
  • connection_timeout: Connection timeout in seconds (default: 30)
  • heartbeat_interval: Heartbeat interval in seconds (default: 10)

​
Setting Up Data Directory

Before running a node, initialize the data directory:
1

Create the data directory

mkdir -p data
2

Copy empty database templates

If available in the repository:
cp crates/database/sql/empty.db data/blockchain.db
cp crates/database/sql/empty.db data/private.db
Otherwise, the databases will be created automatically on first run.
3

Set appropriate permissions

chmod 700 data
chmod 600 data/*.db
The private.db file contains sensitive data. Ensure it has restricted permissions.

​
Initializing the Blockchain

After configuration, initialize the blockchain with genesis data: 
cargo run -- init --source setup_constituencies.sql
Expected output: 
INFO  ubu_block] Blockchain was successfully initialized!

​
Genesis Data

The initialization SQL file should contain:
  • Positions: Election positions (President, Governor, MP, etc.)
  • Parties: Political parties
  • Counties: Geographic regions
  • Constituencies: Electoral constituencies
  • Wards: Subdivisions within constituencies
  • Stations: Polling stations
  • Candidates: Candidates for each position
See the Blockchain Structure guide for details.

​
Environment Variables

Some settings can be configured via environment variables: 
# Logging level
export RUST_LOG=info

# Custom config path
export UBU_CONFIG_PATH=/etc/ubu-block/config.toml

# Database connection pool size
export DATABASE_MAX_CONNECTIONS=10

​
Logging Configuration

Control log verbosity with RUST_LOG: 
# Show all logs
export RUST_LOG=debug

# Show only errors
export RUST_LOG=error

# Module-specific logging
export RUST_LOG=ubu_block=debug,sqlx=warn

​
Production Configuration

production.toml
# Database paths
main_db = "sqlite:///var/lib/ubu-block/blockchain.db"
private_db = "sqlite:///var/lib/ubu-block/private.db"

# Bind to all interfaces
http_addr = "0.0.0.0:9091"
node_addr = "0.0.0.0:9090"

# P2P configuration
[peer_config]
max_connections = 100
connection_timeout = 60
heartbeat_interval = 15

# Production peers
[[peers]]
name = "frankfurt-node"
address = "157.230.123.45:9090"

[[peers]]
name = "backup-node"
address = "192.168.1.100:9090"

​
Security Considerations

Set strict permissions on configuration and database files:
chmod 600 config.toml
chmod 600 data/private.db
chmod 644 data/blockchain.db
Open only necessary ports:
# Allow P2P port
sudo ufw allow 9090/tcp

# Allow HTTP API (submission nodes only)
sudo ufw allow 9091/tcp
For production HTTP APIs, use a reverse proxy with TLS:
server {
    listen 443 ssl;
    server_name api.example.com;
    
    ssl_certificate /etc/ssl/certs/cert.pem;
    ssl_certificate_key /etc/ssl/private/key.pem;
    
    location / {
        proxy_pass http://127.0.0.1:9091;
    }
}
Regularly backup the blockchain database:
# Backup script
sqlite3 /var/lib/ubu-block/blockchain.db ".backup /backup/blockchain-$(date +%Y%m%d).db"

​
Configuration Validation

Validate your configuration before running in production: 
# Test database connectivity
sqlite3 data/blockchain.db "SELECT 1;"

# Verify node starts without errors
cargo run -- --config config.toml --dry-run

# Check port availability
netstat -tuln | grep 9090

​
Next Steps

Running Nodes

Start and manage different node types

Monitoring

Monitor node health and performance

Build docs developers (and LLMs) love

Get started for freeTalk to us