Getting started with your first Valkey instance
Before we tweak settings and tune for performance, let’s get Valkey up and running. The simplest, most repeatable way? Use Docker, as it gives you a clean slate every time, no matter your OS.
1. Run Valkey with Docker
Pop open your terminal and run this command:
docker run -d --name my-valkey-server -p 6379:6379 valkey/valkey-server:7
Here’s a quick breakdown:
- docker run: Spins up a new container.
- -d: Runs the container in "detached" mode, so it runs in the background.
- --name my-valkey-server: Gives your container a friendly, memorable name.
- -p 6379:6379: Connects your local port 6379 to the container, so you can reach it.
- valkey/valkey-server:7: Tells Docker to use the official Valkey image for version 7.
2. Connect with the Command Line Interface (CLI)
Now, let’s talk to your server. With Docker, you can do:
docker exec -it my-valkey-server valkey-cli
If it connects successfully, your terminal prompt will change to 127.0.0.1:6379>.
3. Run your first commands
Let’s make sure everything is working as expected.
First, test the connection with the PING command. It’s the universal "Are you there?" check.
127.0.0.1:6379> PING
PONG
The PONG response means your server is alive and listening. Now, let's try storing and retrieving a piece of data with SET and GET.
127.0.0.1:6379> SET community "Valkey"
OK
127.0.0.1:6379> GET community
"Valkey"
If you get “Valkey” back, everything’s working. Now let’s get your setup ready for real-world use.
The essential configuration (valkey.conf)
A default Valkey install is wide open, with few guardrails. The real security and stability come from the valkey.conf file. There are a lot of settings you could tweak, but some are absolute must-haves for production.
Security first: Lock down your server
If you only do one thing, do this. An unconfigured Valkey server is an open door, and securing it is your top priority.
- Bind to a private IP (bind) This controls where Valkey listens for connections. By default, it only talks to itself (127.0.0.1). If your app runs elsewhere, switch to your server’s private IP, but never use 0.0.0.0 on an internet-facing server unless you know your firewall is airtight. # Only allow connections from the local machine and a specific private IP bind 127.0.0.1 192.168.1.10
- Enable protected mode (protected-mode) This is a built-in safety net. If your server ends up exposed, protected mode will block outside connections until you fix the settings. # Keep this on. It's a critical safety feature.
protected-mode yes
- Require a password (requirepass) Always set a strong, unique password. It’s your main line of defense. # Use a long, complex password here
requirepass your-very-strong-and-secret-password
Memory management: Set limits before it’s too late
Valkey lives in RAM. If you don’t set limits, it will eat up all your memory and take your server down.
- Set a memory limit (maxmemory)
A good starting point: 50-75% of your total RAM. # Example for a server with 16GB of RAM
maxmemory 8gb
- Choose an eviction policy (maxmemory-policy)
So, what happens when Valkey hits its maxmemory limit? This policy tells it what to do. The default, noeviction, simply returns errors for all write commands, which can quickly break your application.
For most use cases, you should change this. The best general-purpose choice is allkeys-lru, which tells Valkey to remove the "least recently used" key to make space. # Remove the least recently used keys when memory is full.
maxmemory-policy allkeys-lru
Logging and daemonization: Running like a service
For a production system, you need Valkey running reliably in the background, not in an active terminal window.
- Run as a background process (daemonize) This keeps Valkey running after you close your terminal. daemonize yes
- Specify a log file (logfile) Always set a log file, so you don’t miss important warnings. logfile /var/log/valkey/valkey-server.log
Data durability: Configuring persistence
Valkey, by default, is in-memory. If it goes down, so does your data, unless you turn on persistence.
Valkey’s primary mechanism for durability is the Append-Only File (AOF).
- Enable the append-only file (appendonly) When you enable AOF, Valkey keeps a log file where it writes every single command that changes your data (like SET, HSET, DEL, etc.). When Valkey restarts, it reads this log from top to bottom and re-executes all the commands to perfectly rebuild its state. This is the most reliable way to prevent data loss. # Enable AOF persistence to protect your data.
appendonly yes
- Configure how often to save (appendfsync) This setting controls how often Valkey saves the AOF log from memory to the disk. You have a few options, but the default choice is the best one for 99% of use cases.
- everysec: Valkey saves the data to disk once every second. This gives you a great balance of performance and safety. In a worst-case scenario, you might lose up to one second of data, which is an acceptable trade-off for most applications.
- always: Saves after every single command. This is extremely safe but can be much slower.
- no: Lets the operating system decide when to save. This is fast but risky.
For production systems, stick with the default. # This is the default and recommended setting for a good balance.
appendfsync everysec
Get these four areas locked down—security, memory, logging, and persistence—and you’ve got a strong, production-ready baseline.
Common pitfalls and how to avoid them
Let’s talk about the most frequent ways people get tripped up and how to dodge those issues from the start.
Pitfall #1: Freezing your server with the KEYS command
It’s tempting to use KEYS "user:*" to find matching keys. In development, that’s fine. In production, it’s a recipe for disaster; Valkey will freeze while scanning every key.
Safe move: Use SCAN instead. It grabs keys in small chunks without blocking everything else.
Pitfall #2: Wiping out your data by accident
FLUSHDB and FLUSHALL can erase everything in a blink. No warning, no undo.
Safe move: Disable or rename these commands in your config: rename-command FLUSHALL ""
rename-command FLUSHDB ""
You can use this technique to rename other powerful commands (like CONFIG) to something long and secret, so they can't be used maliciously or accidentally.
Pitfall #3: Forgetting the fundamentals from day one
The final pitfall is simply ignoring the foundational advice from section 2. Those configurations are your primary defense against the two most common silent killers of a Valkey instance.
- The silent memory leak: Not setting maxmemory is the most common mistake. Your dataset will grow silently, day by day, until it consumes all available RAM and crashes your server at the worst possible moment.
- The surprise data loss: Choosing not to enable AOF persistence for important data is a valid strategy, but only if it's a conscious one. The pitfall is not thinking about it at all, assuming your data is safe, and only discovering it was volatile when a simple server reboot wipes it all away.
By avoiding these common traps, you're not just setting up Valkey correctly; you're developing the habits to use it correctly.
Building for resilience with replication
Even the best single server can fail. Replication gives you a safety net by copying your data in real time to a backup server.
How it works:
Your main Valkey server (the Leader) takes all the writes. The backup server (the Follower) keeps itself synced, ready to take over if needed.
Set it up:
Set it up:
On your Follower, add this to valkey.conf:
replicaof 192.168.1.100 6379
masterauth <your-leader-server-password>
After restarting, your Follower will connect and start syncing.
Check your setup:
Run INFO replication on both servers to confirm everything’s working.
For true high availability, look into automated failover systems. These tools can promote a backup automatically if your main server goes down, keeping your application online with minimal fuss.
Performance tuning and proactive health checks
A stable and secure Valkey instance is great, but it also needs to be fast.
Client-side performance: How your app should talk to Valkey
The biggest performance gains often come from optimizing the communication between your application and Valkey.
- Batch with pipelining: Instead of sending commands one by one, batch them together. You’ll see a big boost in speed.
- Use a connection pool: Reuse network connections instead of making new ones for every request. This cuts down on overhead and latency.
- Organize data with hashes: Keep related fields under one key using Valkey hashes. It’s cleaner and more memory-efficient.
Server-side monitoring: Keeping an eye on Valkey's health
Don't wait for your users to report that your site is slow. Valkey gives you the tools you need to be proactive.
- Check health with INFO: The INFO command is your dashboard. Check it regularly to catch issues early.
- Track down slow commands with SLOWLOG: Use the SLOWLOG feature to find out exactly which commands are dragging things down.
By combining smart client habits with regular monitoring, you’ll keep your Valkey instance quick and healthy. Now, let's bring it all together and discuss your next steps for building with Valkey.
Wrapping up: Setting yourself up for Valkey success
You’ve made it through. If you've followed along, you now have a comprehensive understanding of what it takes to run a production-ready Valkey instance. Here’s a quick recap:
- Lock down your server before you do anything else.
- Set memory limits and smart eviction to avoid crashes.
- Turn on persistence if your data matters.
- Write efficient code and monitor Valkey’s health proactively.
And while you’re now equipped with the fundamentals, some issues may call for an extra set of expert hands.
Need expert help with your Valkey deployment?
This guide covers the essentials for a healthy Valkey setup, but as your application grows, you will likely face more complex challenges. Scaling to handle massive traffic, implementing advanced security protocols, or conducting in-depth performance audits requires deep expertise. As a new open source project, finding trusted, enterprise-grade support can be a challenge.
Don't leave your mission-critical applications to chance.
If you need help with any of these areas, our team at Percona provides enterprise-grade support and services for Valkey, with 24/7 availability. Whether you're dealing with an immediate issue, need a performance audit, or want a long-term partner to help you scale, we're here to make sure your Valkey environment stays secure, stable, and performing at its absolute best.
