Installation

Prerequisites

Before installing Sol RPC Router, ensure you have the following dependencies installed:

Rust (Required)

Sol RPC Router requires Rust 2021 edition or later.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify your Rust installation:

rustc --version
# Should show: rustc 1.70.0 (or higher)

cargo --version
# Should show: cargo 1.70.0 (or higher)

If you already have Rust installed, update to the latest stable version:

rustup update stable

Redis (Required)

Redis is required for API key storage and atomic rate limiting.

Docker
Ubuntu / Debian
macOS
From Source

The easiest way to run Redis:

docker run -d \
  --name sol-rpc-redis \
  -p 6379:6379 \
  redis:7-alpine

To persist data across restarts:

docker run -d \
  --name sol-rpc-redis \
  -p 6379:6379 \
  -v redis-data:/data \
  redis:7-alpine redis-server --appendonly yes

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

Verify installation:

redis-cli ping
# Should return: PONG

Using Homebrew:

brew install redis
brew services start redis

Verify installation:

redis-cli ping
# Should return: PONG

wget https://download.redis.io/redis-stable.tar.gz
tar -xzvf redis-stable.tar.gz
cd redis-stable
make
make install
redis-server

Production Redis Setup: For production deployments, configure Redis with persistence, authentication, and resource limits. See the Redis production checklist for details.

Building from Source

Clone the Repository

git clone https://github.com/glamsystems/sol-rpc-router
cd sol-rpc-router

Build the Project

Build the release version (optimized for production):

cargo build --release

This will compile:

sol-rpc-router - The main proxy server
rpc-admin - The API key management CLI

Build Time: The first build may take 5-10 minutes as Cargo downloads and compiles all dependencies. Subsequent builds will be much faster.

For development (faster compilation, no optimizations):

cargo build

Verify the Build

Check that both binaries were created:

ls -lh target/release/sol-rpc-router
ls -lh target/release/rpc-admin

Run the version check:

./target/release/sol-rpc-router --help
./target/release/rpc-admin --help

Optional: Install System-Wide

Install the binaries to your system PATH:

cargo install --path .

This installs to ~/.cargo/bin/ which should be in your PATH. Now you can run:

sol-rpc-router --config config.toml
rpc-admin create my-client --rate-limit 50

Dependencies

Sol RPC Router uses the following key dependencies (automatically managed by Cargo):

Core Runtime

Dependency	Version	Purpose
`tokio`	1.x	Async runtime with full features
`axum`	0.7	Web framework with WebSocket support
`hyper`	1.x	HTTP client and server
`hyper-tls`	0.6	TLS support for HTTPS backends

Data & Serialization

Dependency	Version	Purpose
`serde`	1.x	Serialization framework
`serde_json`	1.x	JSON parsing and generation
`toml`	0.8	Configuration file parsing

Redis & Caching

Dependency	Version	Purpose
`redis`	0.27	Redis client with async support
`moka`	0.12	Local API key cache (60s TTL)

WebSocket

Dependency	Version	Purpose
`tokio-tungstenite`	0.24	WebSocket client and server
`futures-util`	0.3	Stream utilities for WebSocket

Monitoring

Dependency	Version	Purpose
`metrics`	0.24	Metrics collection framework
`metrics-exporter-prometheus`	0.16	Prometheus metrics exporter

Utilities

Dependency	Version	Purpose
`clap`	4.x	Command-line argument parsing
`tracing`	0.1	Structured logging
`rand`	0.8	Random API key generation
`arc-swap`	1.8	Lock-free config reloading

All dependencies are specified in Cargo.toml and are automatically downloaded and compiled by cargo build.

Configuration Files

Create your configuration file based on the example:

cp config.example.toml config.toml

See the Configuration Guide for detailed documentation of all configuration options.

Running Tests

Sol RPC Router includes 35+ unit and integration tests. All tests use mocks only—no Redis or real HTTP backends required.

# Run all tests
cargo test

# Run tests with output
cargo test -- --nocapture

# List all test names
cargo test -- --list

# Run a specific test
cargo test test_load_config

Expected output:

running 35 tests
test config::tests::test_load_config ... ok
test handlers::tests::test_auth_cache ... ok
test health::tests::test_health_state ... ok
...
test result: ok. 35 passed; 0 failed; 0 ignored

System Requirements

Minimum Requirements

CPU: 1 core (2+ recommended)
RAM: 512 MB (1 GB+ recommended for production)
Disk: 100 MB for binaries + space for logs
OS: Linux, macOS, or Windows with WSL2

Recommended Production Setup

CPU: 4+ cores
RAM: 4 GB+ (depends on API key cache size and request volume)
Disk: SSD for Redis persistence
Network: Low-latency connection to Solana RPC backends
OS: Linux (Ubuntu 22.04 LTS or similar)

Redis Memory: The API key cache uses approximately 1 KB per cached key. With 10,000 active keys, expect ~10 MB of RAM for the cache plus Redis overhead.

Port Requirements

Sol RPC Router uses three ports:

Port	Service	Configurable Via	Default
HTTP	JSON-RPC endpoint	`port` in config.toml	28899
WebSocket	Dedicated WS endpoint	`port + 1` (automatic)	28900
Metrics	Prometheus metrics	`metrics_port` in config.toml	28901

The WebSocket port is always HTTP port + 1 and cannot be configured separately. Ensure both ports are available.

Environment Variables

The rpc-admin CLI supports environment variables:

# Set default Redis URL
export REDIS_URL="redis://127.0.0.1:6379/0"

# Now you can omit --redis-url flag
rpc-admin create my-client --rate-limit 50

The main router reads all configuration from config.toml and does not use environment variables.

Troubleshooting Build Issues

Linker errors on Linux

Error: linking with cc failed or cannot find -lsslSolution: Install development libraries:

# Ubuntu/Debian
sudo apt install build-essential pkg-config libssl-dev

# RHEL/CentOS/Fedora
sudo yum install gcc openssl-devel

Compilation errors with older Rust

Error: error[E0658]: use of unstable library featureSolution: Update Rust to the latest stable version:

rustup update stable
rustup default stable

Out of memory during compilation

Error: LLVM ERROR: out of memory or system hangsSolution: Reduce parallel compilation jobs:

cargo build --release -j 2

Or increase system swap space.

Redis connection issues

Error: Failed to initialize Redis KeyStoreSolutions:

Verify Redis is running: redis-cli ping
Check Redis is listening: netstat -tlnp | grep 6379
Test connection: redis-cli -u redis://127.0.0.1:6379/0 ping
Check firewall rules
Verify redis_url in config.toml is correct

Permission denied on port binding

Error: Permission denied (os error 13) when starting routerSolution: Ports below 1024 require root privileges. Either:

Use ports above 1024 (recommended): port = 8899
Run with sudo (not recommended for production)
Use systemd socket activation
Configure port forwarding with iptables

Next Steps

Quick Start

Get your router running in 5 minutes

Configuration

Learn about all configuration options

Deployment

Deploy to production

Monitoring

Set up Prometheus and Grafana

Get Started

Configuration

Features

Operations

Prerequisites

Rust (Required)

Redis (Required)

Building from Source

Dependencies

Core Runtime

Data & Serialization

Redis & Caching

WebSocket

Monitoring

Utilities

Configuration Files

Running Tests

System Requirements

Minimum Requirements

Recommended Production Setup

Port Requirements

Environment Variables

Troubleshooting Build Issues

Next Steps

Quick Start

Configuration

Deployment

Monitoring

Build docs developers (and LLMs) love

Get Started

Configuration

Features

Operations

​Prerequisites

​Rust (Required)

​Redis (Required)

​Building from Source

​Dependencies

​Core Runtime

​Data & Serialization

​Redis & Caching

​WebSocket

​Monitoring

​Utilities

​Configuration Files

​Running Tests

​System Requirements

​Minimum Requirements

​Recommended Production Setup

​Port Requirements

​Environment Variables

​Troubleshooting Build Issues

​Next Steps

Quick Start

Configuration

Deployment

Monitoring

Build docs developers (and LLMs) love

Prerequisites

Rust (Required)

Redis (Required)

Building from Source

Dependencies

Core Runtime

Data & Serialization

Redis & Caching

WebSocket

Monitoring

Utilities

Configuration Files

Running Tests

System Requirements

Minimum Requirements

Recommended Production Setup

Port Requirements

Environment Variables

Troubleshooting Build Issues

Next Steps