RALE Getting Started
Set up your first consensus cluster
Complete guide to setting up RALE distributed consensus and key-value store system for high availability applications.
Quick Start Guide
1
Install RALE
Download and install all RALE components (librale, raled, ralectrl)
2
Use librale Library
Integrate librale core library into your C applications
3
Configure raled Daemon
Set up and start the RALE cluster management daemon
4
Control with ralectrl
Manage cluster operations using the command-line interface
Installation Steps
1
Install RALE Binary
# Prerequisites
sudo apt-get update
sudo apt-get install -y build-essential cmake libpthread-stubs0-dev git
# Clone and build RALE from source
git clone https://github.com/pgElephant/rale.git
cd rale
# Build all components (always use build script)
./build.sh
# Build creates three main components:
# - librale: Core consensus library (lib/librale.so)
# - raled: Cluster management daemon (bin/raled)
# - ralectrl: Command-line control utility (bin/ralectrl)
# Install system-wide (optional)
sudo make install
# Verify installation
raled --version
ralectrl --help
ldconfig -p | grep librale2
Use librale Library in Your Application
# Example: Advanced librale integration with error handling
#include <librale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <signal.h>
static volatile int running = 1;
void signal_handler(int sig) {
printf("Received signal %d, shutting down...\n", sig);
running = 0;
}
int main() {
rale_context_t *ctx;
char buffer[1024];
size_t len;
int result;
/* Set up signal handlers */
signal(SIGINT, signal_handler);
signal(SIGTERM, signal_handler);
/* Create RALE context */
ctx = librale_context_create();
if (ctx == NULL) {
fprintf(stderr, "Failed to create RALE context\n");
return 1;
}
/* Initialize cluster */
result = librale_cluster_init();
if (result != LIBRALE_SUCCESS) {
fprintf(stderr, "Failed to initialize cluster: %d\n", result);
librale_context_destroy(ctx);
return 1;
}
/* Add cluster nodes */
librale_cluster_add_node(1, "node1", "127.0.0.1", 7400, 7500);
librale_cluster_add_node(2, "node2", "127.0.0.1", 7401, 7501);
librale_cluster_add_node(3, "node3", "127.0.0.1", 7402, 7502);
/* Initialize RALE consensus */
result = librale_rale_init(1, "./rale_data");
if (result != LIBRALE_SUCCESS) {
fprintf(stderr, "Failed to initialize RALE: %d\n", result);
librale_cleanup();
librale_context_destroy(ctx);
return 1;
}
/* Initialize distributed store */
result = librale_dstore_init("./rale_data");
if (result != LIBRALE_SUCCESS) {
fprintf(stderr, "Failed to initialize DStore: %d\n", result);
librale_cleanup();
librale_context_destroy(ctx);
return 1;
}
/* Start services */
librale_rale_start();
librale_network_start(7400, 7500);
printf("RALE services started successfully\n");
/* Store and retrieve data */
const char *key = "user:123:profile";
const char *value = "{\"name\": \"John Doe\", \"email\": \"john@example.com\"}";
result = librale_dstore_put(key, value, strlen(value));
if (result == LIBRALE_SUCCESS) {
printf("Stored: %s = %s\n", key, value);
} else {
fprintf(stderr, "Failed to store data: %d\n", result);
}
/* Retrieve data */
len = sizeof(buffer);
result = librale_dstore_get(key, buffer, &len);
if (result == LIBRALE_SUCCESS) {
buffer[len] = '\0';
printf("Retrieved: %s = %s\n", key, buffer);
} else {
fprintf(stderr, "Failed to retrieve data: %d\n", result);
}
/* Monitor leadership changes */
int current_leader = -1;
while (running) {
int leader_id;
if (librale_rale_get_leader(&leader_id) == LIBRALE_SUCCESS) {
if (leader_id != current_leader) {
printf("Leadership changed: Node %d is now leader\n", leader_id);
current_leader = leader_id;
}
}
sleep(5);
}
/* Cleanup */
printf("Shutting down RALE services...\n");
librale_cleanup();
librale_context_destroy(ctx);
return 0;
}
/* Compile with: gcc -o rale_app rale_app.c -lrale -lpthread */3
Configure and Start raled Daemon
# /etc/raled/raled.conf
[cluster]
name = "my-rale-cluster"
nodes = ["127.0.0.1:7400", "127.0.0.1:7401", "127.0.0.1:7402"]
# Node configuration format: "ip:rale_port"
# Each node must have unique ports
[raft]
election_timeout = 150ms # Leader election timeout
heartbeat_interval = 50ms # Heartbeat frequency
snapshot_interval = 1000 # Log snapshot frequency
max_log_entries = 10000 # Maximum log entries before snapshot
commit_timeout = 100ms # Commit operation timeout
[storage]
data_directory = "/var/lib/raled/data"
max_log_size = 100MB # Maximum log file size
wal_directory = "/var/lib/raled/wal"
snapshot_directory = "/var/lib/raled/snapshots"
compression_enabled = true
compression_level = 6
[network]
rale_port = 7400 # Consensus protocol port
dstore_port = 7500 # Distributed store port
bind_address = "0.0.0.0" # Network binding address
connection_timeout = 30s # Connection timeout
keepalive_interval = 10s # TCP keepalive interval
max_connections = 100 # Maximum concurrent connections
[logging]
level = "info" # Log level: debug, info, warn, error
log_file = "/var/log/raled/raled.log"
max_log_size = 100MB
log_rotation = true
log_retention_days = 30
[security]
tls_enabled = false # Enable TLS encryption
tls_cert_file = "/etc/ssl/certs/raled.crt"
tls_key_file = "/etc/ssl/private/raled.key"
tls_ca_file = "/etc/ssl/certs/ca.crt"4
Control Cluster with ralectrl
# Create data directories
sudo mkdir -p /var/lib/raled/{data,wal,snapshots}
sudo mkdir -p /var/log/raled
sudo chown -R $(whoami):$(whoami) /var/lib/raled /var/log/raled
# Start single node (foreground)
raled --config conf/raled1.conf --log-level debug
# Or start as daemon
raled --config conf/raled1.conf --daemon --pid-file /var/run/raled.pid
# Start three-node cluster (separate terminals)
# Terminal 1:
raled --config conf/raled1.conf --daemon
# Terminal 2:
raled --config conf/raled2.conf --daemon
# Terminal 3:
raled --config conf/raled3.conf --daemon
# Use CLI to manage cluster
ralectrl ADD --node-id 1 --node-name "node1" \
--node-ip "127.0.0.1" --rale-port 7400 --dstore-port 7500
ralectrl ADD --node-id 2 --node-name "node2" \
--node-ip "127.0.0.1" --rale-port 7401 --dstore-port 7501
ralectrl ADD --node-id 3 --node-name "node3" \
--node-ip "127.0.0.1" --rale-port 7402 --dstore-port 7502
# Check cluster status
ralectrl STATUS
ralectrl LIST
ralectrl HEALTH
# Monitor cluster in real-time
ralectrl MONITOR --interval 5sRALE Architecture & Components
librale
Core consensus and distributed store library written in C.
- • RALE consensus algorithm for leader election
- • Distributed key-value storage with replication
- • Thread-safe API for multi-threaded applications
- • TCP/UDP communication with automatic failover
- • Memory-safe allocation/deallocation
raled
Cluster management daemon for coordination and monitoring.
- • Cluster membership management
- • Leader election and failover coordination
- • Persistent cluster state and configuration
- • Inter-node communication and client APIs
- • Health checks and metrics collection
ralectrl
Command-line interface for cluster management and operations.
- • Node management (ADD, REMOVE, LIST)
- • Status queries and cluster health
- • Runtime configuration updates
- • Debug information and troubleshooting
- • JSON output for automation
System Architecture
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Client │ │ Client │ │ Client │
│ Application │ │ Application │ │ Application │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
┌──────────────────┼──────────────────┐
│ │ │
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ raled │ │ raled │ │ raled │
│ (Node 1) │◄──►│ (Node 2) │◄──►│ (Node 3) │
└─────────────┘ └─────────────┘ └─────────────┘
▲ ▲ ▲
│ │ │
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ ralectrl │ │ ralectrl │ │ ralectrl │
│ (CLI) │ │ (CLI) │ │ (CLI) │
└─────────────┘ └─────────────┘ └─────────────┘
Consensus Algorithm
- • Leader Election: Automatic leader selection with majority voting
- • Log Replication: Consistent state across all cluster nodes
- • Split-Brain Prevention: Quorum-based decisions during network partitions
- • Fast Recovery: Sub-second leader election times
Distributed Store
- • Strong Consistency: All reads return the most recent write
- • High Performance: 10,000+ operations/second per node
- • Durability: Write-ahead logging with periodic snapshots
- • Replication: Automatic replication across cluster nodes
Network Layer
- • Fault-Tolerant: Automatic reconnection with exponential backoff
- • Protocol Support: TCP/UDP with heartbeat keepalives
- • Security: Optional TLS encryption and authentication
- • Load Distribution: Requests distributed across available nodes
Performance
- • Consensus: 1000+ operations/second per cluster
- • Write Latency: <10ms for local cluster writes
- • Read Latency: <1ms for local reads
- • Scalability: Optimized for 3-7 node clusters
Advanced Features & Troubleshooting
Advanced Features
Distributed Key-Value Store
- • Strong Consistency: Linearizable reads and writes
- • Automatic Replication: Data replicated across all nodes
- • Compression: Built-in data compression for efficiency
- • Snapshots: Periodic snapshots for fast recovery
Security & TLS
- • TLS Encryption: End-to-end encryption for all communications
- • Certificate Management: X.509 certificate support
- • Access Control: Fine-grained permissions system
- • Audit Logging: Complete audit trail for security events
Monitoring & Metrics
- • Prometheus Metrics: Comprehensive metrics export
- • Health Checks: Built-in health monitoring
- • Performance Metrics: Latency, throughput, and error rates
- • Cluster Metrics: Node status, leadership changes, replication lag
Troubleshooting Guide
Common Issues
Node Won't Start:
- • Check port availability:
netstat -tulpn | grep :7400 - • Verify data directory permissions
- • Check configuration file syntax
Cluster Split-Brain:
- • Ensure odd number of nodes (3, 5, 7)
- • Check network connectivity between nodes
- • Verify firewall rules
High Latency:
- • Monitor network latency between nodes
- • Check disk I/O performance
- • Adjust heartbeat intervals
Debug Commands
# Check cluster status ralectrl STATUS --verbose # View detailed logs raled --config conf/raled1.conf --log-level debug # Test connectivity ralectrl PING --node-id 2 # Monitor real-time ralectrl MONITOR --interval 1s # Check node health ralectrl HEALTH --all-nodes # View configuration ralectrl CONFIG --show # List all nodes ralectrl LIST --detailed
Performance Tuning
- • Election Timeout: Adjust based on network latency
- • Heartbeat Interval: Balance between responsiveness and overhead
- • Snapshot Frequency: Optimize for your data growth rate
- • Connection Pooling: Configure max connections per node
Production Deployment Best Practices
Infrastructure
- • Use dedicated servers for each node
- • Ensure low-latency network connections
- • Use SSDs for data directories
- • Configure proper firewall rules
Security
- • Enable TLS encryption
- • Use strong authentication
- • Regular security updates
- • Monitor access logs
Monitoring
- • Set up Prometheus metrics
- • Configure alerting rules
- • Monitor cluster health
- • Track performance metrics
What's Next?
Your RALE cluster is ready! Explore these next steps.