Skip to main content

​
Overview

This guide will help you build Kora from source, start the server, and run your first commands. You’ll be up and running in under 5 minutes.

​
Prerequisites

  • Rust 1.82+ (edition 2021)
  • Git
  • redis-cli (optional, for testing)
1
Clone the repository
2
Clone the Kora repository from GitHub:
3
git clone https://github.com/Augani/Kora.git
cd kora
4
Build from source
5
Build the release binary using Cargo:
6
cargo build --release
7
The first build may take a few minutes as Cargo downloads and compiles dependencies. Subsequent builds will be much faster.
8
The compiled binary will be located at ./target/release/kora-cli.
9
Start the server
10
Start Kora with default settings (localhost:6379, auto-detected worker count):
11
./target/release/kora-cli
12
You should see output similar to:
13
2026-03-10T12:00:00.000Z  INFO kora_cli: Starting Kōra v0.1.0 with 4 shard-IO workers
2026-03-10T12:00:00.001Z  INFO kora_server::shard_io: Shard 0 bound to 127.0.0.1:6379
2026-03-10T12:00:00.001Z  INFO kora_server::shard_io: Shard 1 bound to 127.0.0.1:6379
2026-03-10T12:00:00.001Z  INFO kora_server::shard_io: Shard 2 bound to 127.0.0.1:6379
2026-03-10T12:00:00.001Z  INFO kora_server::shard_io: Shard 3 bound to 127.0.0.1:6379
14
Kora uses SO_REUSEPORT to bind multiple worker threads to the same port, enabling lock-free request distribution.
15
Connect with redis-cli
16
In a new terminal, connect using the standard Redis CLI:
17
redis-cli -p 6379
18
Try basic commands
19
Once connected, try these commands:
20
String operations
127.0.0.1:6379> SET greeting "hello world"
OK
127.0.0.1:6379> GET greeting
"hello world"
127.0.0.1:6379> INCR counter
(integer) 1
127.0.0.1:6379> INCR counter
(integer) 2
Hash operations
127.0.0.1:6379> HSET user:1 name "Augustus" city "Accra"
(integer) 2
127.0.0.1:6379> HGETALL user:1
1) "name"
2) "Augustus"
3) "city"
4) "Accra"
127.0.0.1:6379> HGET user:1 name
"Augustus"
List operations
127.0.0.1:6379> LPUSH tasks "task-1" "task-2" "task-3"
(integer) 3
127.0.0.1:6379> LRANGE tasks 0 -1
1) "task-3"
2) "task-2"
3) "task-1"
127.0.0.1:6379> RPOP tasks
"task-1"
Set operations
127.0.0.1:6379> SADD tags "rust" "cache" "multi-threaded"
(integer) 3
127.0.0.1:6379> SMEMBERS tags
1) "rust"
2) "cache"
3) "multi-threaded"
127.0.0.1:6379> SISMEMBER tags "rust"
(integer) 1
21
Try document database features
22
Kora includes a built-in JSON document database:
23
# Create a collection and insert documents
127.0.0.1:6379> DOC.CREATE users
OK
127.0.0.1:6379> DOC.SET users user:1 '{"name":"Augustus","age":30,"city":"Accra"}'
OK
127.0.0.1:6379> DOC.SET users user:2 '{"name":"Kwame","age":25,"city":"Kumasi"}'
OK
127.0.0.1:6379> DOC.SET users user:3 '{"name":"Ama","age":28,"city":"Accra","email":"[email protected]"}'
OK

# Create secondary indexes
127.0.0.1:6379> DOC.CREATEINDEX users city hash
OK
127.0.0.1:6379> DOC.CREATEINDEX users age sorted
OK

# Query with WHERE clause
127.0.0.1:6379> DOC.FIND users WHERE city = "Accra"
1) "{\"name\":\"Augustus\",\"age\":30,\"city\":\"Accra\"}"
2) "{\"name\":\"Ama\",\"age\":28,\"city\":\"Accra\",\"email\":\"[email protected]\"}"

# Query with complex predicates
127.0.0.1:6379> DOC.FIND users WHERE age > 25 AND city = "Accra"
1) "{\"name\":\"Augustus\",\"age\":30,\"city\":\"Accra\"}"
2) "{\"name\":\"Ama\",\"age\":28,\"city\":\"Accra\",\"email\":\"[email protected]\"}"

# Field projection
127.0.0.1:6379> DOC.GET users user:1 FIELDS name city
"{\"name\":\"Augustus\",\"city\":\"Accra\"}"

# Count documents
127.0.0.1:6379> DOC.COUNT users WHERE age >= 25
(integer) 3

​
Custom Configuration

You can customize Kora’s behavior with command-line flags: 
# Bind to all interfaces on port 7379 with 8 workers
./target/release/kora-cli --bind 0.0.0.0 --port 7379 --workers 8

# Enable debug logging
./target/release/kora-cli --log-level debug

# With password authentication
./target/release/kora-cli --password "s3cret"

​
Embedded Mode

Kora can also be used as an embedded library in your Rust application: 
use kora_embedded::{Config, Database};

// Open an embedded database
let db = Database::open(Config::default());

// String operations
db.set("user:1", b"Augustus");
let val = db.get("user:1"); // Some(b"Augustus")

// Hash operations
db.hset("profile:1", "name", b"Augustus");
db.hset("profile:1", "city", b"Accra");
let name = db.hget("profile:1", "name"); // Some(b"Augustus")

// List operations
db.lpush("queue", &[b"task-1", b"task-2"]);
let tasks = db.lrange("queue", 0, -1);

// Counter operations
db.incr("counter").unwrap(); // 1
db.incr("counter").unwrap(); // 2
The embedded API provides sub-microsecond dispatch latency with zero network overhead.

​
Hybrid Mode

You can combine embedded access with a TCP listener: 
use kora_embedded::{Config, Database};

let db = Database::open(Config::default());

// Start TCP listener (non-blocking)
db.start_listener("127.0.0.1:6379")?;

// Use the database from your application
db.set("key", b"works from both paths");

// External clients can also connect via redis-cli

​
Performance Testing

Test Kora’s performance using memtier_benchmark: 
# Install memtier_benchmark (Ubuntu/Debian)
sudo apt-get install memtier-benchmark

# Run a benchmark
memtier_benchmark -p 6379 -t 4 -c 50 --pipeline=1 \
  --test-time=30 --key-pattern=R:R --ratio=1:1
For production benchmarks, ensure Kora is built with --release and that your system has adequate resources.

​
Next Steps

Installation Guide

Detailed build, configuration, and deployment instructions

Commands

Complete reference for all supported commands

Document Database

Learn about JSON storage, indexes, and queries

Vector Search

Build similarity search with HNSW indexes

​
Troubleshooting

​
Port already in use

If you see “Address already in use”, check for existing processes: 
# Find process using port 6379
lsof -i :6379

# Kill the process or use a different port
./target/release/kora-cli --port 7379

​
Build errors

Ensure you have Rust 1.82 or later: 
rustc --version  # Should show 1.82 or higher
rustup update    # Update Rust if needed

​
Connection refused

Make sure Kora is running and listening on the correct address: 
# Check if Kora is running
ps aux | grep kora-cli

# Test connection
redis-cli -p 6379 PING

Build docs developers (and LLMs) love

Get started for freeTalk to us