Skip to main content

​
System Requirements

​
Minimum Requirements

  • Operating System: Linux (kernel 5.4+), macOS (10.15+), Windows (WSL2)
  • Rust: 1.82 or later (edition 2021)
  • Memory: 512 MB minimum, 2 GB recommended
  • Disk: 100 MB for binary, additional space for data persistence
  • CPU: 4+ cores for optimal multi-threaded performance
  • Memory: 4 GB+ for production workloads
  • Disk: SSD for persistence (WAL + RDB snapshots)
Kora scales linearly with CPU cores. More cores = better throughput.

​
Installing Rust

If you don’t have Rust installed, use rustup: 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
Verify the installation: 
rustc --version  # Should show 1.82 or higher
cargo --version
Kora requires Rust 1.82+ (MSRV). Earlier versions will not compile.

​
Building from Source

1
Clone the repository
2
git clone https://github.com/Augani/Kora.git
cd kora
3
Build the workspace
4
Build all crates in release mode:
5
cargo build --release
6
This compiles the entire workspace:
7
  • kora-core — data structures and shard engine
  • kora-protocol — RESP2 parser/serializer
  • kora-server — TCP/Unix server
  • kora-embedded — library mode API
  • kora-storage — WAL + RDB persistence
  • kora-vector — HNSW vector search
  • kora-cdc — change data capture
  • kora-doc — JSON document database
  • kora-pubsub — pub/sub messaging
  • kora-observability — metrics and stats
  • kora-cli — CLI binary
    • 8
    The first build takes 5-10 minutes. Subsequent builds are incremental and much faster.
    9
    Verify the build
    10
    Check that the binary was created:
    11
    ls -lh ./target/release/kora-cli
    12
    You should see a binary of approximately 8-12 MB (stripped).
    13
    Run tests (optional)
    14
    Run the full test suite to verify everything works:
    15
    # Run all workspace tests
cargo test --workspace

# Run tests for a specific crate
cargo test -p kora-core
cargo test -p kora-protocol

# Run integration tests
cargo test --test integration -p kora-server
    16
    Run linters (optional)
    17
    Ensure code quality:
    18
    # Run clippy (lint checks)
cargo clippy --workspace --all-targets

# Format code
cargo fmt --all

    ​
    Installation Options

    ​
    Option 1: Run from build directory

    Run Kora directly from the build directory: 
    ./target/release/kora-cli --port 6379 --workers 4

    ​
    Option 2: Install to system path

    Install the binary to ~/.cargo/bin (automatically in PATH): 
    cargo install --path kora-cli

# Now you can run from anywhere
kora --port 6379

    ​
    Option 3: Copy to custom location

    Copy the binary to a custom location: 
    sudo cp ./target/release/kora-cli /usr/local/bin/kora
sudo chmod +x /usr/local/bin/kora

# Run from anywhere
kora --port 6379

    ​
    Configuration

    Kora supports three layers of configuration, applied in order of precedence:
    1. Built-in defaults — sensible defaults for local development
    2. TOML config file — persistent configuration
    3. CLI arguments — runtime overrides

    ​
    CLI Arguments

    All configuration options are available as command-line flags: 
    kora-cli \
  --bind 0.0.0.0 \
  --port 6379 \
  --workers 8 \
  --log-level info \
  --password "s3cret" \
  --data-dir /var/lib/kora \
  --snapshot-interval-secs 300 \
  --snapshot-retain 24 \
  --cdc-capacity 65536 \
  --metrics-port 9090 \
  --unix-socket /tmp/kora.sock

    ​
    Common CLI Flags

    FlagDefaultDescription
    --bind127.0.0.1Address to bind to
    --port6379TCP port to listen on
    --workersCPU coresNumber of shard worker threads
    --log-levelinfoLog level (trace, debug, info, warn, error)
    --passwordNoneOptional AUTH password
    --data-dirNoneData directory for persistence
    --configkora.tomlPath to TOML config file
    --metrics-port0Prometheus metrics HTTP endpoint (0 = disabled)
    --unix-socketNoneOptional Unix socket path

    ​
    TOML Configuration File

    Create a kora.toml file for persistent configuration: 
    bind = "0.0.0.0"
port = 6379
workers = 8
log_level = "info"
password = "s3cret"
cdc_capacity = 65536
metrics_port = 9090
unix_socket = "/tmp/kora.sock"

[storage]
data_dir = "/var/lib/kora"
wal_sync = "every_second"   # every_write | every_second | os_managed
wal_enabled = true
rdb_enabled = true
snapshot_interval_secs = 300
snapshot_retain = 24
wal_max_bytes = 67108864  # 64 MB
    Load the config file: 
    # Uses kora.toml in current directory by default
kora-cli

# Or specify a custom path
kora-cli --config /etc/kora/kora.toml
    CLI arguments override config file values. This allows environment-specific overrides while keeping base configuration in the file.

    ​
    Storage Configuration

    Kora supports three persistence modes:

    ​
    1. In-Memory Only (Default)

    No persistence — data lost on restart: 
    kora-cli --port 6379

    ​
    2. Write-Ahead Log (WAL)

    Durable, append-only log with configurable sync policy: 
    [storage]
data_dir = "/var/lib/kora"
wal_enabled = true
wal_sync = "every_second"  # every_write | every_second | os_managed
wal_max_bytes = 67108864   # Auto-rotate at 64 MB
    Sync Policies:
    • every_write — Fsync after every write (slowest, most durable)
    • every_second — Fsync every second (balanced)
    • os_managed — Let OS decide (fastest, least durable)

    ​
    3. RDB Snapshots

    Periodic atomic snapshots with CRC verification: 
    [storage]
data_dir = "/var/lib/kora"
rdb_enabled = true
snapshot_interval_secs = 300  # Snapshot every 5 minutes
snapshot_retain = 24          # Keep last 24 snapshots
    Combine both for optimal durability and recovery: 
    [storage]
data_dir = "/var/lib/kora"
wal_enabled = true
wal_sync = "every_second"
rdb_enabled = true
snapshot_interval_secs = 300
snapshot_retain = 24
wal_max_bytes = 67108864

    ​
    Environment Setup

    ​
    Create data directory

    sudo mkdir -p /var/lib/kora
sudo chown $USER:$USER /var/lib/kora

    ​
    Set log level via environment

    export RUST_LOG=kora=debug,kora_server=trace
kora-cli

    ​
    Increase file descriptor limit

    For high-concurrency workloads: 
    # Temporary (current shell)
ulimit -n 65536

# Permanent (add to /etc/security/limits.conf)
* soft nofile 65536
* hard nofile 65536

    ​
    Running as a Service

    ​
    systemd (Linux)

    Create /etc/systemd/system/kora.service: 
    [Unit]
Description=Kora Cache Engine
After=network.target

[Service]
Type=simple
User=kora
Group=kora
WorkingDirectory=/var/lib/kora
ExecStart=/usr/local/bin/kora --config /etc/kora/kora.toml
Restart=always
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
    Enable and start the service: 
    sudo systemctl daemon-reload
sudo systemctl enable kora
sudo systemctl start kora
sudo systemctl status kora
    View logs: 
    sudo journalctl -u kora -f

    ​
    Docker

    Create a Dockerfile: 
    FROM rust:1.82 as builder

WORKDIR /build
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    libssl3 \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /build/target/release/kora-cli /usr/local/bin/kora

EXPOSE 6379
VOLUME ["/data"]

ENTRYPOINT ["kora"]
CMD ["--bind", "0.0.0.0", "--data-dir", "/data"]
    Build and run: 
    docker build -t kora:latest .
docker run -d -p 6379:6379 -v kora-data:/data --name kora kora:latest

    ​
    Verification Steps

    1
    Check the server is running
    2
    ps aux | grep kora-cli
    3
    Test connectivity
    4
    redis-cli -p 6379 PING
# Expected: PONG
    5
    Check server info
    6
    redis-cli -p 6379 INFO
    7
    Test basic operations
    8
    redis-cli -p 6379 SET test:key "hello"
redis-cli -p 6379 GET test:key
# Expected: "hello"
    9
    Monitor metrics (if enabled)
    10
    curl http://localhost:9090/metrics

    ​
    Build Options

    ​
    Development Build

    Faster compilation, slower runtime: 
    cargo build
./target/debug/kora-cli
    Optimized for production: 
    cargo build --release
./target/release/kora-cli

    ​
    Profile-Guided Optimization (PGO)

    For maximum performance: 
    # Step 1: Build instrumented binary
RUSTFLAGS="-Cprofile-generate=/tmp/pgo-data" cargo build --release

# Step 2: Run representative workload
./target/release/kora-cli &
memtier_benchmark -p 6379 -t 4 -c 50 --test-time=60
killall kora-cli

# Step 3: Merge profiling data
llvm-profdata merge -o /tmp/pgo-data/merged.profdata /tmp/pgo-data

# Step 4: Build with profile data
RUSTFLAGS="-Cprofile-use=/tmp/pgo-data/merged.profdata" cargo build --release

    ​
    Feature Flags

    Kora uses Cargo features for optional functionality: 
    # Build without server features (embedded only)
cargo build --release --no-default-features -p kora-embedded

# Build with additional features
cargo build --release --features server

    ​
    Troubleshooting

    ​
    Compilation Errors

    Error: Rust version too old 
    rustup update
rustc --version  # Verify 1.82+
    Error: Linker not found 
    # Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install

    ​
    Runtime Issues

    Error: Address already in use 
    # Find what's using the port
lsof -i :6379

# Use a different port
kora-cli --port 7379
    Error: Permission denied (data directory) 
    # Fix permissions
sudo chown -R $USER:$USER /var/lib/kora
    Error: Too many open files 
    # Increase file descriptor limit
ulimit -n 65536

    ​
    Performance Issues

    Low throughput
    • Ensure you built with --release
    • Check worker count matches CPU cores: --workers $(nproc)
    • Monitor CPU usage: top or htop
    • Check for disk I/O bottlenecks if using persistence
    High latency
    • Use every_second or os_managed WAL sync policy
    • Disable persistence for testing: remove --data-dir
    • Check network latency: ping your server

    ​
    Next Steps

    Quick Start

    Start using Kora with basic commands

    Configuration

    Advanced configuration options

    Commands

    Complete command reference

    Production Deployment

    Deploy Kora in production

    Build docs developers (and LLMs) love

    Get started for freeTalk to us