KeyDB 6.3.4 (Ubuntu 24.04) AMI Administrator Guide

1. Quick Start Information

Connection Methods:

Access the instance via SSH using the ubuntu user. Use sudo to run commands requiring root privileges. To switch to the root user, use sudo su - root.

Install Information:

OS: Ubuntu 24.04 LTS
KeyDB version: 6.3.4
Redis compatibility: 6.3.4 (100% Redis API compatible)
Installation Source: KeyDB Official Repository (Jammy 22.04 packages)
Default Port: 6379
Configuration File: /etc/keydb/keydb.conf
Data Directory: /var/lib/keydb

KeyDB Service Management:

Start KeyDB service: sudo systemctl start keydb-server
Stop KeyDB service: sudo systemctl stop keydb-server
Restart KeyDB service: sudo systemctl restart keydb-server
Check KeyDB status: sudo systemctl status keydb-server
Enable auto-start: sudo systemctl enable keydb-server

Quick Verification Commands:

Check KeyDB version: keydb-server --version
Check CLI version: keydb-cli --version
Test connection: keydb-cli ping
Set a key: keydb-cli set test "value"
Get a key: keydb-cli get test
View server info: keydb-cli info server

External Access Configuration (Optional):

Security Note: External access is disabled by default to prevent unauthorized access.

Step 1: Open configuration file: sudo nano /etc/keydb/keydb.conf
Step 2: Allow external connections by changing bind 127.0.0.1 to bind 0.0.0.0
Step 3: Enable password protection by uncommenting and setting the requirepass parameter (e.g., requirepass StrongPassword123!)
Step 4: Save and exit the file (Ctrl+O, Enter, Ctrl+X)
Step 5: Apply changes: sudo systemctl restart keydb-server
Step 6: Connect remotely: keydb-cli -h YOUR_IP -p 6379 -a StrongPassword123!

Firewall Configuration:

Please allow SSH port 22.
Allow KeyDB port 6379 if accessing from external clients.
For security, it is recommended to limit access to trusted IPs only.

2. First Launch & Verification

Step 1: Connect to Your Instance

Launch your instance in your cloud provider's console (e.g., AWS EC2)
Ensure SSH port 22 is allowed in your security group
If accessing KeyDB from external clients, allow port 6379

Connect via SSH:

ssh -i your-key.pem ubuntu@YOUR_PUBLIC_IP

Step 2: Verify KeyDB Installation

Check KeyDB server version:

keydb-server --version

Expected Output:

KeyDB server v=6.3.4 sha=00000000:0 malloc=jemalloc-5.2.1 bits=64 build=b532cd0401cb0da4

Check KeyDB CLI version:

keydb-cli --version

Expected Output:

keydb-cli 6.3.4

Step 3: Verify KeyDB Service Status

Check if KeyDB daemon is running:

sudo systemctl status keydb-server

Expected Output:

● keydb-server.service - Advanced key-value store
     Loaded: loaded (/usr/lib/systemd/system/keydb-server.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-02-13 05:11:09 UTC
   Main PID: 2401 (keydb-server)

Step 4: Test KeyDB Functionality

Test basic Redis commands:

# Test PING command
keydb-cli ping

Expected Output:

PONG

Test SET and GET:

# Set a key
keydb-cli set health_check "OK"

# Get the key
keydb-cli get health_check

Expected Output:

OK
"OK"

Step 5: View Server Information

View server information:

keydb-cli info server | grep _version

Expected Output:

redis_version:6.3.4
gcc_version:11.2.0

3. Architecture & Detailed Configuration

This AMI uses KeyDB, a high-performance fork of Redis. KeyDB is 100% API-compatible with Redis while offering up to 5x higher throughput.

Installation Architecture:

[KeyDB Official Repository]
         ↓
[keydb 6.3.4] → /usr/bin/keydb-server
[keydb-tools] → /usr/bin/keydb-cli
         ↓
[Configuration Files]
         ↓
/etc/keydb/keydb.conf → Main configuration
         ↓
[Systemd Service]
         ↓
keydb-server.service → Auto-start on boot

Key Design Decisions:

Jammy Repository: Using Ubuntu 22.04 packages (stable and tested on 24.04)
Redis Compatible: 100% API compatibility - drop-in replacement for Redis
Jemalloc Allocator: Optimized memory allocation for high-performance workloads
Auto-Start: KeyDB service enabled to start automatically on boot

Why KeyDB Over Redis?

Feature	Redis	KeyDB
Throughput	Baseline	Up to 5x higher
API Compatibility	-	100% compatible
Active Replication	No	Yes (Active-Replica)
Flash Storage	No	Yes (FLASH support)
License	BSD-3-Clause	BSD-3-Clause

3.1. Main Configuration File

File Location: /etc/keydb/keydb.conf

Key Settings (Partial):

# Network
bind 127.0.0.1 -::1
protected-mode yes
port 6379

# General
daemonize yes
supervised systemd
pidfile /run/keydb/keydb-server.pid

# Snapshotting (persistence)
save 900 1
save 300 10
save 60 10000
dbfilename dump.rdb
dir /var/lib/keydb

# Logging
loglevel notice
logfile /var/log/keydb/keydb-server.log

# Security
requirepass <your-password-here>

How This Works:

bind 127.0.0.1: Listens on localhost only (change to 0.0.0.0 for external access)
protected-mode yes: Requires authentication for external connections
save: RDB persistence snapshots (saves to disk periodically)
dir /var/lib/keydb: Data directory for RDB files

3.2. KeyDB Repository Configuration

File Location: /etc/apt/sources.list.d/keydb.list

File Content:

deb [signed-by=/etc/apt/trusted.gpg.d/keydb.gpg] https://download.keydb.dev/open-source-dist jammy main

GPG Key Location: /etc/apt/trusted.gpg.d/keydb.gpg

How This Works:

jammy: Ubuntu 22.04 codename (used because noble/24.04 packages not yet available)
signed-by: Verifies package signatures with KeyDB's GPG key
main: Stable release channel

Why Jammy Repository on Noble?

KeyDB has not yet released noble-specific packages
Jammy (22.04) packages are fully compatible with noble (24.04)
Verified stable and tested

4. How-To-Create: Reproduce This Environment

This section explains how this AMI was built, allowing you to reproduce the installation on any Ubuntu 24.04 system.

Step 1: Clean Up Old Configurations

Purpose: Remove any existing KeyDB configurations or conflicting packages.

# Remove old sources and keys
sudo rm -f /etc/apt/sources.list.d/keydb.list
sudo rm -f /etc/apt/trusted.gpg.d/keydb.gpg

# Update package index
sudo apt update

How This Works:

Ensures a clean installation
Prevents conflicts from previously attempted installations
Clears old GPG keys that might cause signature verification issues

Step 2: Add KeyDB Official Repository

Purpose: Configure apt to use KeyDB's official package repository.

# Download and install official GPG key
sudo wget -O /etc/apt/trusted.gpg.d/keydb.gpg https://download.keydb.dev/open-source-dist/keyring.gpg

# Add KeyDB repository (using Jammy packages)
echo "deb [signed-by=/etc/apt/trusted.gpg.d/keydb.gpg] https://download.keydb.dev/open-source-dist jammy main" | sudo tee /etc/apt/sources.list.d/keydb.list

# Update package index with new repository
sudo apt update

# Install KeyDB
sudo apt install -y keydb

How This Works:

wget -O: Downloads GPG key to specific location
/etc/apt/trusted.gpg.d/: Directory for trusted package signing keys
signed-by: Associates repository with specific GPG key (modern apt format)
jammy main: Specifies Ubuntu 22.04 stable channel

Package Installation:

The keydb package includes:

keydb-server: Main server binary
keydb-cli: Command-line interface
keydb-tools: Additional utilities
Default configuration files
Systemd service unit

Step 3: Enable and Start KeyDB

Purpose: Enable the KeyDB service to start automatically on boot.

# Enable and start KeyDB
sudo systemctl enable keydb-server
sudo systemctl start keydb-server

How This Works:

systemctl enable: Configures KeyDB to start automatically on system boot
systemctl start: Starts the KeyDB service immediately

5. Using the KeyDB Environment

5.1. Basic Commands (Redis-Compatible)

Connect to KeyDB:

keydb-cli

Inside the CLI:

127.0.0.1:6379> SET mykey "Hello KeyDB"
OK
127.0.0.1:6379> GET mykey
"Hello KeyDB"
127.0.0.1:6379> INCR counter
(integer) 1
127.0.0.1:6379> EXPIRE mykey 300
(integer) 1
127.0.0.1:6379> TTL mykey
(integer) 298
127.0.0.1:6379> EXIT

5.2. Working with Data Structures

Strings:

keydb-cli SET user:1000:name "Alice"
keydb-cli GET user:1000:name

Lists:

keydb-cli LPUSH tasks "task1" "task2" "task3"
keydb-cli LRANGE tasks 0 -1
keydb-cli RPOP tasks

Hashes:

keydb-cli HSET user:1001 name "Bob" age 30 city "NYC"
keydb-cli HGET user:1001 name
keydb-cli HGETALL user:1001

Sets:

keydb-cli SADD tags "redis" "keydb" "database"
keydb-cli SMEMBERS tags
keydb-cli SISMEMBER tags "keydb"

Sorted Sets:

keydb-cli ZADD leaderboard 100 "player1" 200 "player2" 150 "player3"
keydb-cli ZRANGE leaderboard 0 -1 WITHSCORES
keydb-cli ZREVRANGE leaderboard 0 2 WITHSCORES

5.3. Performance Benchmarking

Run benchmark:

keydb-benchmark -q -n 100000

Expected Output:

PING_INLINE: 140000.00 requests per second
PING_BULK: 142000.00 requests per second
SET: 135000.00 requests per second
GET: 138000.00 requests per second
INCR: 140000.00 requests per second

Benchmark specific command:

keydb-benchmark -t set,get -n 100000 -q

5.4. Monitoring and Statistics

View server info:

keydb-cli info

Key sections:

# Server info
keydb-cli info server

# Memory usage
keydb-cli info memory

# Statistics
keydb-cli info stats

# Replication
keydb-cli info replication

Monitor commands in real-time:

keydb-cli monitor

Check connected clients:

keydb-cli client list

5.5. Enabling External Access

Edit main configuration:

sudo nano /etc/keydb/keydb.conf

Change bind address:

# Before
bind 127.0.0.1 -::1

# After (allow all interfaces)
bind 0.0.0.0

Set password for security:

requirepass YourStrongPasswordHere

Restart KeyDB:

sudo systemctl restart keydb-server

Connect with password:

keydb-cli -a YourStrongPasswordHere
# or
keydb-cli
127.0.0.1:6379> AUTH YourStrongPasswordHere

6. Important File Locations

File Path	Purpose
`/usr/bin/keydb-server`	KeyDB server binary
`/usr/bin/keydb-cli`	KeyDB command-line interface
`/etc/keydb/keydb.conf`	Main configuration file
`/var/lib/keydb/`	Data directory (RDB files)
`/var/log/keydb/keydb-server.log`	KeyDB log file
`/run/keydb/keydb-server.pid`	Process ID file
`/etc/apt/sources.list.d/keydb.list`	KeyDB repository configuration
`/etc/apt/trusted.gpg.d/keydb.gpg`	KeyDB GPG signing key
`/usr/lib/systemd/system/keydb-server.service`	Systemd service file

7. Troubleshooting

Issue 1: KeyDB Service Not Starting

Symptoms:

$ sudo systemctl start keydb-server
Job for keydb-server.service failed

Diagnosis:

Check service status:

sudo systemctl status keydb-server

View logs:

sudo journalctl -u keydb-server -n 50 --no-pager

Common Causes:

Port already in use:

sudo lsof -i :6379

Solution: Kill conflicting process or change port in config.

Permission issues:

sudo chown -R keydb:keydb /var/lib/keydb
sudo chmod 750 /var/lib/keydb

Invalid configuration:

Test configuration:

keydb-server /etc/keydb/keydb.conf --test-memory 1

Issue 2: Cannot Connect to KeyDB

Symptoms:

$ keydb-cli ping
Could not connect to KeyDB at 127.0.0.1:6379: Connection refused

Diagnosis:

Check if KeyDB is running:

sudo systemctl status keydb-server

Solution:

Start KeyDB:

sudo systemctl start keydb-server

If still failing, check bind address in config:

grep "^bind" /etc/keydb/keydb.conf

Issue 3: Memory Usage Too High

Symptoms:

KeyDB consuming excessive memory.

Diagnosis:

Check memory usage:

keydb-cli info memory | grep used_memory_human

Solutions:

Set max memory limit:

Edit /etc/keydb/keydb.conf:

maxmemory 2gb
maxmemory-policy allkeys-lru

Enable RDB compression:

rdbcompression yes

Clear unnecessary data:

keydb-cli FLUSHALL

Restart KeyDB:

sudo systemctl restart keydb-server

Issue 4: Slow Performance

Symptoms:

Queries taking longer than expected.

Diagnosis:

Run benchmark:

keydb-benchmark -q -n 100000

Check slow queries:

keydb-cli SLOWLOG GET 10

Solutions:

Disable persistence for maximum speed:

Edit config:

save ""
appendonly no

Tune TCP settings:

sudo sysctl -w net.core.somaxconn=65535

Increase max clients:

maxclients 10000

Issue 5: Data Loss After Restart

Symptoms:

All data disappears after KeyDB restart.

Diagnosis:

Check persistence settings:

grep "^save" /etc/keydb/keydb.conf
grep "^appendonly" /etc/keydb/keydb.conf

Solution:

Enable RDB persistence:

save 900 1
save 300 10
save 60 10000

Or enable AOF (Append-Only File):

appendonly yes
appendfilename "appendonly.aof"

Restart KeyDB:

sudo systemctl restart keydb-server

8. Final Notes

Key Takeaways

KeyDB 6.3.4 is installed and ready to use
5x performance compared to Redis
100% Redis compatible - drop-in replacement
The installation is production-ready and AMI-optimized

KeyDB Use Cases

High-Throughput Caching: Session storage, API response caching
Real-Time Analytics: Counting, leaderboards, time-series data
Message Queues: Pub/sub, task queues, event streaming
Database Acceleration: Query result caching, read replicas
Gaming: Player data, matchmaking, real-time scoreboards

KeyDB vs Redis Comparison

Scenario	Redis	KeyDB
Multi-client workload	Baseline	Up to 5x faster
Active-active replication	No	Yes
Flash storage support	No	Yes
Drop-in replacement	-	Yes

Additional Resources

Official KeyDB Documentation: https://docs.keydb.dev/
KeyDB GitHub: https://github.com/Snapchat/KeyDB
Redis Commands Reference: https://redis.io/commands/
KeyDB Blog: https://docs.keydb.dev/blog/
Performance Benchmarks: https://docs.keydb.dev/docs/benchmarking/

Support

If you encounter issues not covered in this guide:

Check the troubleshooting section above
Review KeyDB official documentation
Verify your security group and firewall settings
Check KeyDB logs: sudo journalctl -u keydb-server -n 100

For support or questions, please contact the Easycloud team.

1. Quick Start Information​

2. First Launch & Verification​

Step 1: Connect to Your Instance​

Step 2: Verify KeyDB Installation​

Step 3: Verify KeyDB Service Status​

Step 4: Test KeyDB Functionality​

Step 5: View Server Information​

3. Architecture & Detailed Configuration​

3.1. Main Configuration File​

3.2. KeyDB Repository Configuration​

4. How-To-Create: Reproduce This Environment​

Step 1: Clean Up Old Configurations​

Step 2: Add KeyDB Official Repository​

Step 3: Enable and Start KeyDB​

5. Using the KeyDB Environment​

5.1. Basic Commands (Redis-Compatible)​

5.2. Working with Data Structures​

5.3. Performance Benchmarking​

5.4. Monitoring and Statistics​

5.5. Enabling External Access​

6. Important File Locations​

7. Troubleshooting​

Issue 1: KeyDB Service Not Starting​

Issue 2: Cannot Connect to KeyDB​

Issue 3: Memory Usage Too High​

Issue 4: Slow Performance​

Issue 5: Data Loss After Restart​

8. Final Notes​

Key Takeaways​

KeyDB Use Cases​

KeyDB vs Redis Comparison​

Additional Resources​

Support​

1. Quick Start Information

2. First Launch & Verification

Step 1: Connect to Your Instance

Step 2: Verify KeyDB Installation

Step 3: Verify KeyDB Service Status

Step 4: Test KeyDB Functionality

Step 5: View Server Information

3. Architecture & Detailed Configuration

3.1. Main Configuration File

3.2. KeyDB Repository Configuration

4. How-To-Create: Reproduce This Environment

Step 1: Clean Up Old Configurations

Step 2: Add KeyDB Official Repository

Step 3: Enable and Start KeyDB

5. Using the KeyDB Environment

5.1. Basic Commands (Redis-Compatible)

5.2. Working with Data Structures

5.3. Performance Benchmarking

5.4. Monitoring and Statistics

5.5. Enabling External Access

6. Important File Locations

7. Troubleshooting

Issue 1: KeyDB Service Not Starting

Issue 2: Cannot Connect to KeyDB

Issue 3: Memory Usage Too High

Issue 4: Slow Performance

Issue 5: Data Loss After Restart

8. Final Notes

Key Takeaways

KeyDB Use Cases

KeyDB vs Redis Comparison

Additional Resources

Support