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

TagBuild
v1.2.2Default (recommended): no Lua or TLS. The fastest build; the benchmark results are from it.
v1.2.2-luaLua scripting (EVAL / EVALSHA)
v1.2.2-tlsTLS-encrypted connections
v1.2.2-fullLua and TLS
latestThe 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, then INFO, 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 with docker cp <name>:/home/kividb/dump.kdb ..
  • Health checks can't run redis-cli in the container. ["CMD", "kividb", "--version"] only proves the binary runs. Use a TCP check on the port instead, or run redis-cli ping from 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).

FlagDefaultDescription
--requirepassnonePassword clients must AUTH with
--aofoffAppend-only file persistence
--threads0 (auto)Worker threads. 0 uses cores − 2 (all cores below 4).
--databases16Number of databases
--maxmemory0Memory limit in bytes, or with a unit (512mb, 3gb). 0 = unlimited.
--loglevelinfodebug, verbose, notice (or info), warning, nothing
--io-modelautoI/O model: auto, uring, tokio
--port6380Port to listen on inside the container
--protected-modeyes (no in the image's default command)Refuse clients from other hosts while there is no password

Cluster mode (optional)

FlagDefaultDescription
--cluster-enabled <yes|no>noEnable cluster mode and open a cluster bus on port + 10000.
--cluster-node-timeout <ms>15000Failure 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.