Redis

Redis is an in-memory data store used as a cache, session store, queue and simple database. It keeps data in RAM and can persist it to disk with snapshots (RDB) and an append-only file (AOF). Valkey is a compatible fork that uses the same commands and redis-cli-style tools.

Documentation: Redis docs · Commands · redis-cli · Persistence

Verification: the redis-cli options (--bigkeys, --memkeys, --keystats, --scan, --latency) and the Docker image tags were checked against the Redis docs and Docker Hub. Not verified against the docs: ACL, replication and persistence settings below (they come from the Redis documentation as known, not re-read). No command was executed. Commands like FLUSHALL and KEYS * are dangerous on a real instance.

See also: Docker · Docker-Compose · PostgreSQL Cheat-Sheet · MongoDB · Linux · Linux Performance Troubleshooting

Run in Docker #

docker run -d --name redis --restart unless-stopped \
  -p 127.0.0.1:6379:6379 \
  -v redis-data:/data \
  redis:8 \
  redis-server --appendonly yes --requirepass <PASSWORD>

docker exec -it redis redis-cli -a '<PASSWORD>' ping

Compose:

services:
  redis:
    image: redis:8
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]
    volumes:
      - redis-data:/data
    ports:
      - "127.0.0.1:6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
volumes:
  redis-data:

Mount /data or the data is lost with the container. Do not expose port 6379 to the internet. See Docker and Docker-Compose. Prefer --requirepass or an ACL file over a password on the command line in production (it shows in ps). Pin a major version tag (redis:7, redis:8).

Install on Ubuntu / Debian #

sudo apt update && sudo apt install -y redis-server
sudo systemctl enable --now redis-server
redis-cli ping

Config: /etc/redis/redis.conf. For a current version use the official packages repository.

redis-cli #

--bigkeys, --memkeys and --keystats scan the whole keyspace. Run them against a replica or off-hours on large instances.

Inside redis-cli #

Data Types #

SET greeting "hello" EX 300
HSET user:1 name alice email alice@example.com
HGETALL user:1
RPUSH jobs '{"id":1}'
BRPOP jobs 5
ZADD scores 42 alice 17 bob
ZREVRANGE scores 0 9 WITHSCORES

Use a naming convention such as app:object:id and always set TTLs on cache keys.

Persistence #

redis.conf:

# RDB: snapshot after 3600 s if >=1 change, 300 s if >=100, 60 s if >=10000
save 3600 1 300 100 60 10000
dbfilename dump.rdb
dir /data

# AOF
appendonly yes
appendfsync everysec
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb

Back up by copying dump.rdb (after BGSAVE) or the AOF directory (appendonlydir/ in 7+) while Redis runs, or with redis-cli --rdb. To restore, stop Redis, put the file in dir, start. If AOF is enabled it takes precedence over dump.rdb on start, so move the old AOF away or restore the AOF itself. Keep copies off the host.

Memory and eviction:

maxmemory 512mb
maxmemory-policy allkeys-lru

Run Redis with vm.overcommit_memory=1 on the host so snapshots and rewrites (which fork) do not fail: echo 'vm.overcommit_memory = 1' | sudo tee /etc/sysctl.d/99-redis.conf && sudo sysctl --system. Disable Transparent Huge Pages if Redis warns about it.

Security and ACLs #

Defaults: bind to localhost only, protected mode on. Keep it that way, and always use a password or ACL when it is reachable by anything but localhost.

redis.conf basics:

bind 127.0.0.1 -::1
protected-mode yes
requirepass <LONG-RANDOM-PASSWORD>
rename-command FLUSHALL ""

(rename-command is deprecated: prefer ACLs.)

ACLs (Redis 6+):

Rule syntax: on|off, >password, ~keypattern, &channelpattern, +command, -command, +@category. The passwords above are placeholders: use your own and keep them out of shell history.

Use TLS for traffic across hosts (tls-port, tls-cert-file, tls-key-file, tls-ca-cert-file), or keep Redis on a private network or a WireGuard tunnel.

Replication #

A replica copies a primary asynchronously and serves reads.

On the replica (redis.conf) or at runtime:

replicaof <PRIMARY-HOST> 6379
masterauth <PRIMARY-PASSWORD>
masteruser <ACL-USER-IF-USED>
replica-read-only yes

Notes:

• Replication is asynchronous. A failover can lose the last writes.
• A new replica does a full sync: the primary forks, writes an RDB and sends it. Plan memory headroom.
• Automatic failover needs Redis Sentinel (three or more sentinels, SENTINEL config, clients that support it) or Redis Cluster for sharding. For a homelab a single instance with AOF is usually enough.
• Docker: give the replica command: redis-server --replicaof redis 6379 on a shared network.

Troubleshooting #

redis-benchmark -q -n 100000 gives a quick throughput test (run it against a test instance).