--- title: "How to Install KeyDB on Ubuntu 24.04 as a Redis Alternative" description: "Install KeyDB on Ubuntu 24.04 with Docker, secure it with a password, enable multithreading and active replication, and migrate data from an existing Redis." category: "Caching and CDN" language: en source: https://cubepath.com/docs/caching-and-cdn/keydb-as-redis-alternative-installation updated: 2026-09-25 --- # How to Install KeyDB on Ubuntu 24.04 as a Redis Alternative KeyDB is a fork of Redis that serves requests from several threads instead of one, speaks the same protocol and reads the same configuration format, so existing Redis clients and libraries work without changes. Its two main additions are multithreading, which raises throughput on servers with several cores, and active replication, where two nodes replicate to each other and both accept writes. In this tutorial you will run KeyDB on Ubuntu 24.04 with the official Docker image, secure it, tune its threads, set up active replication between two servers and migrate data from Redis. > Note: The latest KeyDB release is 6.3.4, published in October 2023, and it is compatible with Redis 6.2. KeyDB's APT repository has no packages for Ubuntu 24.04, which is why this guide uses the official `eqalpha/keydb` Docker image. Check the project's recent activity on GitHub before choosing it for a new production system. ## Prerequisites To follow this tutorial you need: - A server running Ubuntu 24.04 LTS with at least 2 GB of RAM and 2 or more CPU cores, for example a CubePath VPS, and a non-root user with `sudo` privileges. - Docker Engine with the Compose plugin. Step 1 installs it. - For Step 6, a second Ubuntu 24.04 server on the same private network. The guide calls their private addresses `node1_private_ip` and `node2_private_ip`. - For Step 7, an existing Redis 6 server reachable from the KeyDB server. ## Step 1 - Installing Docker Install Docker Engine from Docker's official repository: ```bash sudo apt update sudo apt install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` Verify the installation: ```bash sudo docker run --rm hello-world ``` ```output Hello from Docker! This message shows that your installation appears to be working correctly. ``` ## Step 2 - Writing the KeyDB configuration Create a directory for KeyDB that only root can enter, because the configuration file will contain the password: ```bash sudo install -d -m 700 /opt/keydb sudo install -d /opt/keydb/data ``` Generate a long random password. Hex characters avoid any quoting problems in the configuration file: ```bash openssl rand -hex 32 ``` Copy the output, then create the configuration file: ```bash sudo nano /opt/keydb/keydb.conf ``` ```ini bind 0.0.0.0 port 6379 protected-mode yes requirepass your_keydb_password dir /data appendonly yes appendfsync everysec save 900 1 save 300 10 maxmemory 1gb maxmemory-policy allkeys-lru server-threads 2 ``` Replace `your_keydb_password` with the value you generated. The settings mean: - `bind 0.0.0.0` makes KeyDB listen on every interface inside the container. Which interface of the server it is reachable on is decided by Docker in the next step. - `requirepass` forces every client to authenticate. - `appendonly yes` writes every change to an append-only file, flushed once per second, and the `save` lines add periodic snapshots, so a restart loses at most about one second of writes. - `maxmemory` and `allkeys-lru` make KeyDB evict the least recently used keys when it reaches 1 GB, which is what you want for a cache. For data that must never be evicted, use `noeviction` instead and size `maxmemory` accordingly. - `server-threads 2` enables two worker threads. Step 4 explains how to tune it. ## Step 3 - Starting KeyDB with Docker Compose Create the Compose file: ```bash sudo nano /opt/keydb/compose.yaml ``` ```yaml services: keydb: image: eqalpha/keydb:latest container_name: keydb restart: unless-stopped command: ["keydb-server", "/etc/keydb/keydb.conf"] ports: - "127.0.0.1:6379:6379" volumes: - ./keydb.conf:/etc/keydb/keydb.conf:ro - ./data:/data ``` The port is published on `127.0.0.1` only, so applications on this server can connect but nothing outside can. The `latest` tag points to 6.3.4, the last release. Start the container: ```bash cd /opt/keydb sudo docker compose up -d ``` To avoid typing the password on the command line, read it from the configuration file into a shell variable for this session: ```bash KEYDB_PASSWORD=$(sudo awk '/^requirepass/ {print $2}' /opt/keydb/keydb.conf) ``` Check that KeyDB answers and that authentication is enforced: ```bash sudo docker exec keydb keydb-cli ping sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" ping ``` ```output NOAUTH Authentication required. PONG ``` Confirm the version and that the data directory is being used: ```bash sudo docker exec keydb keydb-server --version sudo ls /opt/keydb/data ``` ```output KeyDB server v=6.3.4 sha=00000000:0 malloc=jemalloc-5.2.1 bits=64 build=... appendonly.aof ``` ### Connecting applications KeyDB accepts the same connection strings as Redis. An application on this server connects with: ```text redis://:your_keydb_password@127.0.0.1:6379/0 ``` To use the regular Redis command-line client from the host, install `redis-tools` and pass the password through the `REDISCLI_AUTH` variable: ```bash sudo apt install redis-tools REDISCLI_AUTH="$KEYDB_PASSWORD" redis-cli -h 127.0.0.1 set greeting "hello from keydb" REDISCLI_AUTH="$KEYDB_PASSWORD" redis-cli -h 127.0.0.1 get greeting ``` ```output OK "hello from keydb" ``` ## Step 4 - Tuning multithreading `server-threads` sets how many threads accept and process client requests. KeyDB's own documentation advises relating it to your network throughput rather than to the core count, and not going above 4. A practical rule is 2 threads on a 2 to 4 core server and 4 threads on 8 cores or more, leaving cores free for the operating system and for persistence. Check the core count and the current setting: ```bash nproc sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" config get server-threads ``` ```output 4 1) "server-threads" 2) "2" ``` `server-threads` is read at startup. To change it, edit `/opt/keydb/keydb.conf` and restart the container with `sudo docker compose restart` from `/opt/keydb`. Measure the effect with the bundled benchmark tool, which opens 50 parallel connections and sends 100,000 `SET` and `GET` commands: ```bash sudo docker exec keydb keydb-benchmark -a "$KEYDB_PASSWORD" -c 50 -n 100000 -t set,get -q ``` ```output SET: 142653.36 requests per second, p50=0.183 msec GET: 151975.69 requests per second, p50=0.167 msec ``` Run it with different `server-threads` values on your own hardware. The benchmark runs inside the same container and competes for CPU, so use it to compare settings rather than as an absolute number. The benchmark writes test keys, so run it before loading real data or on a test instance. ## Step 5 - Allowing access from other servers If applications on other servers need KeyDB, publish the port on the private network interface instead of on `127.0.0.1`, and allow only the servers that need it. Never publish KeyDB on a public IP address. Edit the `ports` section of `/opt/keydb/compose.yaml`: ```yaml ports: - "node1_private_ip:6379:6379" ``` Apply the change and allow the client or peer server in the firewall: ```bash cd /opt/keydb sudo docker compose up -d sudo ufw allow from node2_private_ip to any port 6379 proto tcp ``` > Warning: Ports published by Docker are opened in iptables directly and are not filtered by UFW rules. The binding to the private address is what keeps KeyDB off the public internet, so double check the `ports` line. On a CubePath private network, only your own servers can reach the private address. ## Step 6 - Setting up active replication between two nodes With standard Redis replication, one node accepts writes and the replicas are read-only. With KeyDB's active replication, each node is a replica of the other and both accept writes, so an application can write to whichever node is closer or still alive. Repeat Steps 1 to 5 on the second server, using the **same password** on both nodes and publishing the port on each server's private address. Then add the replication settings to `/opt/keydb/keydb.conf` on **node 1**: ```ini active-replica yes replica-read-only no masterauth your_keydb_password replicaof node2_private_ip 6379 ``` On **node 2**, add the same block, pointing to node 1: ```ini active-replica yes replica-read-only no masterauth your_keydb_password replicaof node1_private_ip 6379 ``` `masterauth` is the password each node uses to authenticate against its peer. > Warning: When a replica connects, it discards its own dataset and loads the one from its master. If both nodes already hold different data, the first one to sync wins and the other node's keys are lost. Start with node 1 holding the data and node 2 empty, and restart node 1 first. Restart the container on node 1, then on node 2: ```bash cd /opt/keydb sudo docker compose restart ``` Check the replication status on either node: ```bash sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" info replication | grep -E 'role|master_host|master_link_status' ``` ```output role:active-replica master_host:node2_private_ip master_link_status:up ``` Test writes in both directions. On node 1: ```bash sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" set written_on node1 ``` On node 2, read that key and write another one: ```bash sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" get written_on sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" set reply_from node2 ``` ```output "node1" OK ``` Back on node 1, `get reply_from` returns `"node2"`. Keep in mind that if the same key is written on both nodes at the same moment, the last write to arrive wins; design the application so that each key has a single writer when that matters. ## Step 7 - Migrating data from Redis The least disruptive migration is to make KeyDB a temporary replica of the existing Redis server. KeyDB copies the full dataset and then keeps it in sync until you switch the applications over. This works with Redis 6.x. Redis 7 writes a newer snapshot format that KeyDB 6.3 may not be able to load; if the replication log shows `Can't handle RDB format version`, you need an export and import tool instead. On the Redis server, allow the KeyDB server's address to reach port 6379 on its private interface. Then, on the KeyDB server, set the Redis password and start replicating. Replace `redis_private_ip` and `your_redis_password`: ```bash sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" config set masterauth your_redis_password sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" replicaof redis_private_ip 6379 ``` Wait until the link is up and the key counts match on both sides: ```bash sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" info replication | grep master_link_status sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" dbsize ``` ```output master_link_status:up (integer) 184233 ``` Compare the number with `redis-cli dbsize` on the Redis server. Then point your applications at KeyDB, and once no client writes to Redis any more, promote KeyDB to a standalone server: ```bash sudo docker exec keydb keydb-cli --no-auth-warning -a "$KEYDB_PASSWORD" replicaof no one ``` ```output OK ``` These `config set` and `replicaof` commands change the running server only, so after a restart KeyDB uses `/opt/keydb/keydb.conf` again, which is what you want once the migration is finished. ## Troubleshooting **The container keeps restarting.** Read the log with `sudo docker compose logs --tail 50 keydb` from `/opt/keydb`. A typo in `keydb.conf` shows as `Bad directive or wrong number of arguments` with the line number. **`NOAUTH Authentication required` from an application.** The client is not sending the password. Add it to the connection string or the client options. **`master_link_status:down` on a replica.** Check that the peer is reachable with `nc -zv node2_private_ip 6379`, that the firewall allows it, and that `masterauth` matches the peer's `requirepass`. The container log shows the exact error from the sync attempt. **`OOM command not allowed when used memory > 'maxmemory'`.** The policy is `noeviction` and memory is full. Raise `maxmemory` or switch to an eviction policy such as `allkeys-lru` if the data is a cache. ## Conclusion You now have KeyDB running on Ubuntu 24.04 with authentication, persistence, tuned worker threads and, optionally, active replication between two nodes, and you know how to move data over from Redis without downtime. As next steps, back up `/opt/keydb/data` regularly, monitor memory with `info memory`, and test a node failure to see how your application behaves when one of the two replicas disappears.