Skip to main content
This guide covers everything you need to know about installing, building, and configuring ValKeyper.

​
System Requirements

Go Version

Go 1.22 or later is required to build ValKeyper

Operating System

Linux, macOS, or Windows (with WSL recommended)

Memory

Minimum 512 MB RAM (more for production workloads)

Network

Port 6379 (default) or custom port availability

​
Building from Source

1

Install Go

If you don’t have Go installed, download it from golang.org:
# Verify Go installation
go version
# Should output: go version go1.22 or later
2

Clone the repository

git clone https://github.com/vansh845/valkeyper.git
cd valkeyper
3

Install dependencies

ValKeyper uses minimal dependencies. Download them using:
go mod download
Dependencies:
  • github.com/libp2p/go-reuseport - Socket reuse for better performance
  • Standard Go libraries
4

Build the binary

Build ValKeyper with:
go build -o valkeyper
For optimized production builds:
go build -ldflags="-s -w" -o valkeyper
This reduces the binary size by stripping debug information.
5

Verify the build

Test the binary:
./valkeyper --help

​
Installation Methods

For local development, simply build and run from the project directory:
go build
./valkeyper

​
Configuration Options

ValKeyper supports command-line flags for configuration:

​
Port Configuration

Run ValKeyper on a specific port: 
./valkeyper --port 6380
Default: 6379 (standard Redis port)

​
Persistence Configuration

Configure RDB persistence for loading data from disk: 
./valkeyper --dir /tmp/redis-files --dbfilename dump.rdb
​
--dir
string
Directory where RDB files are stored
​
--dbfilename
string
Name of the RDB file to load on startup
ValKeyper currently supports loading RDB files but does not automatically create snapshots. This feature is planned for future releases.

​
Replication Configuration

Configure ValKeyper as a replica (slave) node: 
./valkeyper --port 6380 --replicaof "127.0.0.1 6379"
​
--replicaof
string
Master server address in format "IP PORT"

​
Configuration File

ValKeyper includes a basic redis.conf configuration file: 
dir /tmp/redis-files
dbfilename dump.rdb
The configuration file is currently used for reference. Command-line flags take precedence.

​
Complete Configuration Example

Here’s a complete example with all options: 
# Start as master on port 6379 with persistence
./valkeyper \
  --port 6379 \
  --dir /var/lib/valkeyper \
  --dbfilename dump.rdb

​
Runtime Information

Query server configuration and status using the CONFIG and INFO commands: 
# Get configured directory
CONFIG GET dir

# Get database filename
CONFIG GET dbfilename

# Get server info
INFO
# Returns:
# role:master
# master_replid:8371b4fb1155b71f4a04d3e1bc3e18c4a990aeeb
# master_repl_offset:0

​
Troubleshooting

If port 6379 is already in use:
# Check what's using the port
lsof -i :6379

# Use a different port
./valkeyper --port 6380
Ensure you have Go 1.22 or later:
go version
Clean the build cache and rebuild:
go clean -cache
go build
Verify the file path and permissions:
# Check if file exists
ls -l /tmp/redis-files/dump.rdb

# Ensure read permissions
chmod 644 /tmp/redis-files/dump.rdb
Check the server output for RDB parsing errors.
Ensure the master is reachable:
# Test connectivity
telnet 127.0.0.1 6379
Verify the master is running:
redis-cli -p 6379 PING

​
Building for Production

For production deployments, build with optimizations: 
# Build optimized binary
CGO_ENABLED=0 go build -ldflags="-s -w" -o valkeyper

# Create dedicated user (Linux)
sudo useradd -r -s /bin/false valkeyper

# Create data directory
sudo mkdir -p /var/lib/valkeyper
sudo chown valkeyper:valkeyper /var/lib/valkeyper

# Run as service user
sudo -u valkeyper ./valkeyper --dir /var/lib/valkeyper
Consider using a process manager like systemd or supervisord to manage the ValKeyper process in production.

​
Source Code Architecture

ValKeyper is organized into several key modules: 
valkeyper/
├── app/
│   ├── server.go       # Main server entry point
│   ├── store/
│   │   └── store.go    # Core key-value store implementation
│   ├── resp/
│   │   └── parser.go   # RESP protocol parser
│   └── rdb/
│       └── rdb.go      # RDB file format parser
├── go.mod              # Go module definition
└── redis.conf          # Configuration reference
Key Components:
  • store.go - In-memory storage, command processing, replication, transactions
  • parser.go - Redis RESP protocol encoding/decoding
  • rdb.go - RDB persistence format parsing
  • server.go - TCP server and connection handling

​
Next Steps

Quickstart

Start using ValKeyper with basic commands

Replication Setup

Configure master-slave replication

Persistence

Learn about RDB file format and data persistence

API Reference

Explore all supported commands

Build docs developers (and LLMs) love

Get started for freeTalk to us