Install with Docker
KiviDB images are published on Docker Hub as {{KIVIDBDOCKERREPO}} and on GitHub's registry as {{KIVIDBGHCRREPO}}, with the same tags. Images are built for…
KiviDB images are published on Docker Hub as kividb/kividb and on GitHub's registry as ghcr.io/kividbio/kividb, with the same tags. Images are built for linux/amd64 and linux/arm64. The examples below use Docker Hub; for GHCR, put ghcr.io/kividbio/ in front of the image name instead of kividb/.
Tags
| Tag | Build |
|---|---|
v1.2.2 | Default (recommended): no Lua or TLS. The fastest build; the benchmark results are from it. |
v1.2.2-lua | Lua scripting (EVAL / EVALSHA) |
v1.2.2-tls | TLS-encrypted connections |
v1.2.2-full | Lua and TLS |
latest | The newest release, Default build |
Pin a version tag in anything you deploy, so the image changes only when you change the tag.
docker pull kividb/kividb:v1.2.2
# or
docker pull ghcr.io/kividbio/kividb:v1.2.2
Run it
docker run -d -p 6380:6380 -v kividb-data:/home/kividb kividb/kividb:v1.2.2
redis-cli -p 6380 ping
# PONG
-v kividb-data:/home/kividb mounts a named volume where KiviDB keeps its data (/home/kividb, the image's working directory), so it survives the container being removed and recreated. Without it, the data is lost with the container.
Flags, and setting a password
A container is reached through its network, never from loopback, so the image's default command is --protected-mode no. Arguments you pass replace that default, which turns protected mode back on: the server then refuses clients from outside the container until it has a password. When you pass your own flags, set a password (recommended) or add --protected-mode no yourself:
docker run -d -p 6380:6380 kividb/kividb:v1.2.2 \
--requirepass "change-me" \
--databases 8 \
--loglevel debug
redis-cli -p 6380 -a "change-me" ping
With AOF persistence
With --aof, every write is appended to appendonly.aof, so a crash loses at most about the last second of writes rather than everything since the last snapshot. Mount a volume so the files outlive the container:
docker run -d -p 6380:6380 \
-v kividb-data:/home/kividb \
kividb/kividb:v1.2.2 --aof --requirepass "change-me"
The server runs as UID 1000 in /home/kividb. To keep the data in a host directory instead, create it owned by UID 1000 first (mkdir -p data && sudo chown 1000:1000 data, then -v "$(pwd)/data:/home/kividb"): a directory Docker creates for a bind mount belongs to root, and the server stops with Permission denied when it opens appendonly.aof.
Docker Compose
services:
kividb:
image: kividb/kividb:v1.2.2
command: ["--aof", "--requirepass", "${KIVIDB_PASSWORD:?set KIVIDB_PASSWORD}"]
environment:
# Turns off the startup update check: the image tag is what you upgrade.
KIVIDB_NO_UPDATE_CHECK: "1"
ports:
- "6380:6380"
volumes:
- kividb-data:/home/kividb
volumes:
kividb-data:
export KIVIDB_PASSWORD="change-me"
docker compose up -d
docker compose logs -f kividb
The update check
Each time it starts, KiviDB makes one HTTPS request to GitHub to see whether a newer release is out, and prints a line if one is. In a container that is every start. Where the image tag decides the version, as in Compose files and Kubernetes, turn it off with KIVIDB_NO_UPDATE_CHECK=1 in the environment, or --update-check no among the arguments.
Debugging a container
The image is distroless: it has the kividb binary and nothing else, so there is no shell, no redis-cli and no ps inside, and docker exec has nothing to run. Debug from outside instead:
- Logs go to standard output:
docker logs <name>. - Run commands from a client in another container on the same network:
docker run --rm -it --network container:<name> redis redis-cli -p 6380, thenINFO,SLOWLOG GET,LATENCY LATEST,CLIENT LIST,MEMORY DOCTOR. - Look at the data files through the volume, from another container:
docker run --rm -v kividb-data:/data busybox ls -l /data, or copy one out withdocker cp <name>:/home/kividb/dump.kdb .. - Health checks can't run
redis-cliin the container.["CMD", "kividb", "--version"]only proves the binary runs. Use a TCP check on the port instead, or runredis-cli pingfrom another container.
io_uring
Docker's default seccomp profile blocks io_uring on recent versions, and KiviDB then falls back to Tokio. To allow it on a Linux host, run with --security-opt seccomp=unconfined, and understand what that permits before using it in production:
docker run -d -p 6380:6380 --security-opt seccomp=unconfined kividb/kividb:v1.2.2
Command-line flags
Pass flags after the image name. Remember that they replace the default --protected-mode no (see above).
| Flag | Default | Description |
|---|---|---|
--requirepass | none | Password clients must AUTH with |
--aof | off | Append-only file persistence |
--threads | 0 (auto) | Worker threads. 0 uses cores − 2 (all cores below 4). |
--databases | 16 | Number of databases |
--maxmemory | 0 | Memory limit in bytes, or with a unit (512mb, 3gb). 0 = unlimited. |
--loglevel | info | debug, verbose, notice (or info), warning, nothing |
--io-model | auto | I/O model: auto, uring, tokio |
--port | 6380 | Port to listen on inside the container |
--protected-mode | yes (no in the image's default command) | Refuse clients from other hosts while there is no password |
Cluster mode (optional)
| Flag | Default | Description |
|---|---|---|
--cluster-enabled <yes|no> | no | Enable cluster mode and open a cluster bus on port + 10000. |
--cluster-node-timeout <ms> | 15000 | Failure detection timeout (lower for faster failover testing). |
See Set up a cluster for forming a multi-node cluster.
Run docker run --rm kividb/kividb:v1.2.2 --help for the full list.