Valkey Deployment and Usage Guide

1. Prerequisites

Operating System Requirements

Valkey builds and runs on:

• Linux (primary platform)
• macOS
• OpenBSD, NetBSD, FreeBSD
• Solaris-derived systems (SmartOS - best effort support)

Both big endian and little endian architectures are supported, as well as 32-bit and 64-bit systems.

Build Dependencies

Install the following system packages:

Debian/Ubuntu:

sudo apt-get install build-essential

RHEL/CentOS/Fedora:

sudo yum groupinstall "Development Tools"
# or
sudo dnf groupinstall "Development Tools"

macOS: Requires Xcode Command Line Tools (xcode-select --install).

Optional Feature Dependencies

Note: For RHEL/CentOS, use systemd-devel instead of libsystemd-dev.

2. Installation

Valkey is built from source. There is no package manager installation; compilation produces the server and client binaries.

Clone the Repository

git clone https://github.com/valkey-io/valkey.git
cd valkey

Standard Build

make

Build with Optional Features

Production build with TLS and systemd support:

make BUILD_TLS=yes USE_SYSTEMD=yes

Development build with debugging symbols:

make CFLAGS="-g -O0" USE_LIBBACKTRACE=yes

Build without Lua scripting engine:

make BUILD_LUA=no

32-bit build (if required):

make 32bit

Verify Installation

Run the test suite to ensure stability:

make test              # Main integration tests
make test-unit         # Unit tests
make test-modules      # Module API tests
make test-sentinel     # Sentinel integration tests
make test-cluster      # Cluster integration tests

Binary Locations

After successful compilation, binaries are located in the project root:

• valkey-server - The database server
• valkey-cli - Command line interface
• valkey-benchmark - Performance testing tool
• valkey-check-aof / valkey-check-rdb - Data file repair utilities
• valkey-sentinel - High availability monitoring (symlink to valkey-server)

3. Configuration

Configuration File

Valkey uses a configuration file (typically valkey.conf). Create your configuration:

cp valkey.conf valkey-custom.conf

Key configuration directives:

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

# Persistence
dir /var/lib/valkey
dbfilename dump.rdb
appendonly yes
appendfilename "appendonly.aof"

# Memory
maxmemory 256mb
maxmemory-policy allkeys-lru

# Logging
logfile /var/log/valkey/valkey.log
loglevel notice

# Security
requirepass your-strong-password

Build-Time Environment Variables

Set these during compilation, not runtime:

Runtime Command-Line Arguments

# Start with config file
./valkey-server /etc/valkey/valkey.conf

# Start with custom port and daemonize
./valkey-server --port 6380 --daemonize yes --loglevel debug

# Start Sentinel mode
./valkey-server /etc/valkey/sentinel.conf --sentinel

4. Build & Run

Development Workflow

1. Clean build (required after dependency updates or architecture changes):

make distclean
make

2. Run unit tests during development:

make test-unit

3. Start development server:

./valkey-server --port 6379 --loglevel verbose

4. Connect via CLI:

./valkey-cli -p 6379 ping

Production Build

Optimized build with all production features:

make distclean
make BUILD_TLS=yes USE_SYSTEMD=yes USE_FAST_FLOAT=yes MALLOC=jemalloc

Run with systemd (if built with USE_SYSTEMD=yes):

./valkey-server /etc/valkey/valkey.conf --supervised systemd

Memory Allocator Selection

For production workloads, ensure jemalloc is active (default on Linux):

# Verify allocator
./valkey-cli INFO memory | grep mem_allocator

If fragmentation issues occur, rebuild with specific allocator:

make MALLOC=libc  # Force system malloc (not recommended for production)

Processor Clock Considerations

On x86_64 Linux and aarch64, Valkey uses the processor's TSC/CNTVCT for 3x faster time access. If experiencing time-related bugs on virtualized or unusual hardware:

make CFLAGS="-DNO_PROCESSOR_CLOCK"  # Force POSIX clock_gettime

5. Deployment

systemd Service Deployment

Create /etc/systemd/system/valkey.service:

[Unit]
Description=Valkey In-Memory Data Store
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/valkey-server /etc/valkey/valkey.conf --supervised systemd
ExecStop=/usr/local/bin/valkey-cli shutdown
Restart=always
User=valkey
Group=valkey

[Install]
WantedBy=multi-user.target

Enable and start:

sudo useradd -r -s /bin/false valkey
sudo mkdir -p /var/lib/valkey /var/log/valkey /etc/valkey
sudo chown valkey:valkey /var/lib/valkey /var/log/valkey
sudo cp valkey-server valkey-cli /usr/local/bin/
sudo cp valkey.conf /etc/valkey/
sudo systemctl daemon-reload
sudo systemctl enable valkey
sudo systemctl start valkey

Cluster Deployment

Minimum 3 master nodes for production:

Node 1:

./valkey-server --port 7000 --cluster-enabled yes --cluster-config-file nodes-7000.conf --cluster-node-timeout 5000 --appendonly yes

Create cluster:

./valkey-cli --cluster create 192.168.1.1:7000 192.168.1.2:7000 192.168.1.3:7000 --cluster-replicas 1

Sentinel Deployment (High Availability)

Configure Sentinel (sentinel.conf):

sentinel monitor mymaster 192.168.1.1 6379 2
sentinel down-after-milliseconds mymaster 60000
sentinel failover-timeout mymaster 180000
sentinel parallel-syncs mymaster 1

Start Sentinel:

./valkey-server sentinel.conf --sentinel
# or
./valkey-sentinel sentinel.conf

Container Deployment

Docker example:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y build-essential libssl-dev
COPY . /valkey
WORKDIR /valkey
RUN make BUILD_TLS=yes
EXPOSE 6379
ENTRYPOINT ["/valkey/src/valkey-server"]

Production container flags:

docker run -v /data:/data -p 6379:6379 valkey:latest \
  --appendonly yes \
  --dir /data \
  --maxmemory 2gb \
  --maxmemory-policy allkeys-lru

Platform-Specific Notes

FreeBSD/OpenBSD: Use gmake instead of make.

macOS: To use jemalloc (recommended):

make MALLOC=jemalloc

32-bit Production Systems: Ensure libc6-dev-i386 and g++-multilib are installed. If build fails:

make CFLAGS="-m32 -march=native" LDFLAGS="-m32"

6. Troubleshooting

Build Issues

Problem: Build fails after git pull or dependency updates Solution:

make distclean
make

Problem: 32-bit to 64-bit (or reverse) architecture switch fails Solution:

make distclean
make  # or make 32bit

Problem: "undefined reference to SSL_*" errors Solution: Ensure OpenSSL development headers are installed:

# Debian/Ubuntu
sudo apt-get install libssl-dev

# RHEL/CentOS
sudo yum install openssl-devel

Problem: fast_float build fails with C++ errors Solution: Verify C++ compiler is installed:

g++ --version  # or clang++
make USE_FAST_FLOAT=yes

Runtime Issues

Problem: High memory fragmentation Solution: Ensure jemalloc is active. Check with INFO memory. If using libc malloc, rebuild:

make distclean
make MALLOC=jemalloc

Problem: Time jump warnings or monotonic clock issues Solution: Disable processor clock:

make CFLAGS="-DNO_PROCESSOR_CLOCK"

Problem: Cannot bind to port or connection refused Solution: Check bind directive in config. For Docker/cloud, bind to 0.0.0.0 (with protected-mode disabled or password set):

bind 0.0.0.0
protected-mode no
requirepass your-password

Problem: Sentinel mode with TLS module not working Solution: Build TLS as built-in, not module:

make BUILD_TLS=yes  # NOT BUILD_TLS=module

Testing Failures

Problem: Test suite fails intermittently Solution: Run specific test categories separately:

make test-unit
make test-modules

Problem: Need to debug specific test Solution: See detailed test documentation:

• Integration tests: tests/README.md
• Unit tests: src/unit/README.md