Skip to main content

Installation

This guide covers all the ways to install and run SierraDB on your system.

The easiest way to run SierraDB is with Docker:

Basic Usage​

# Run SierraDB with default settings
docker run -p 9090:9090 tqwewe/sierradb

With Persistent Data​

# Create a data directory
mkdir sierradb-data

# Run with volume mount for persistence
docker run -p 9090:9090 \
  -v ./sierradb-data:/app/data \
  tqwewe/sierradb

Docker Compose​

Create a docker-compose.yml file:

version: '3.8'
services:
  sierradb:
    image: tqwewe/sierradb
    ports:
      - "9090:9090"
    volumes:
      - ./data:/app/data
    environment:
      - SIERRADB_CLIENT_ADDRESS=0.0.0.0:9090
    restart: unless-stopped

Then run:

docker-compose up -d

Cargo Install​

If you have Rust installed, you can install SierraDB using Cargo:

# Install from crates.io
cargo install sierradb-server

# Run SierraDB
sierradb --dir ./data --client-address 0.0.0.0:9090

System Requirements​

  • Rust 1.88 or later
  • At least 1GB of available RAM
  • SSD storage recommended for best performance

Build from Source​

Prerequisites​

  • Rust toolchain (install from rustup.rs)
  • Git

Build Steps​

# Clone the repository
git clone https://github.com/sierra-db/sierradb.git
cd sierradb

# Build the project
cargo build --release

# The binary will be at target/release/sierradb-server
./target/release/sierradb-server --help

Running from Source​

# Run with default configuration
./target/release/sierradb-server --dir ./data

# Or with custom settings
./target/release/sierradb-server \
  --dir ./data \
  --client-address 0.0.0.0:9090 \
  --cluster-address /ip4/0.0.0.0/tcp/7890

Configuration​

Command Line Options​

sierradb-server --help

Common options:

  • --dir <PATH>: Data directory (default: ./data)
  • --client-address <ADDR>: Client connection address (default: 127.0.0.1:9090)
  • --cluster-address <ADDR>: Cluster communication address
  • --log <LEVEL>: Log level (e.g., info, debug, warn)
  • --config <FILE>: Load configuration from file

Configuration File​

Create a sierradb.toml configuration file:

[bucket]
count = 4

[partition]
count = 32

[segment]
size_bytes = 268435456  # 256MB

[replication]
factor = 1 # Or 3 for cluster

[network]
client_address = "0.0.0.0:9090"
cluster_address = "/ip4/0.0.0.0/tcp/0"

[threads]
read = 8
write = 4

Then run:

sierradb-server --config sierradb.toml

Verification​

Test your installation:

# Connect with redis-cli
redis-cli -p 9090

# Run a simple command
PING
# Should respond with PONG

# Check server info
HELLO 3

Performance Tuning​

For production deployments:

System Configuration​

# Increase file descriptor limits
echo "* soft nofile 65536" >> /etc/security/limits.conf
echo "* hard nofile 65536" >> /etc/security/limits.conf

# Optimize kernel parameters
echo 'vm.swappiness = 1' >> /etc/sysctl.conf              # Minimize swap usage - keeps data in RAM
echo 'vm.dirty_ratio = 15' >> /etc/sysctl.conf            # Flush dirty pages when 15% of RAM is used
echo 'vm.dirty_background_ratio = 5' >> /etc/sysctl.conf  # Start background flushing at 5% of RAM

Cluster Setup​

For distributed deployments, make sure to set replication.factor = 3 in your configuration:

# Node 1
sierradb-server \
  --dir ./node1-data \
  --node-index 0 \
  --node-count 3 \
  --client-address 0.0.0.0:9090

# Node 2
sierradb-server \
  --dir ./node2-data \
  --node-index 1 \
  --node-count 3 \
  --client-address 0.0.0.0:9091

# Node 3
sierradb-server \
  --dir ./node3-data \
  --node-index 2 \
  --node-count 3 \
  --client-address 0.0.0.0:9092

Troubleshooting​

Common Issues​

Port already in use:

# Check what's using port 9090
lsof -i :9090

# Use a different port
sierradb-server --client-address 0.0.0.0:9091

Permission denied:

# Ensure the data directory is writable
chmod 755 ./data

Out of memory:

# Check system memory
free -h

# Reduce thread counts in configuration
[threads]
read = 4
write = 2

Log Analysis​

SierraDB logs to stdout by default. For debugging:

# Run with debug logging
sierradb-server --dir ./data --log debug

# Or save logs to file
sierradb-server --dir ./data 2>&1 | tee sierradb.log

Next Steps​