Requirements: Using Docker

You will need to install Docker on your machine. The repository provides the following Docker images:

1. A release image (Dockerfile.release): a small self-contained image with a pre-built K9db server. Use this to try out or run K9db. A pre-built version is published on Docker Hub, so you do not need to build it yourself.
2. A dev image (Dockerfile.dev): a development environment for building K9db from source, running tests, and running the experiments.

Both images build and run natively on x86_64 and on arm64 (e.g. Apple Silicon Macs).

Release image: running K9db

Using the published image (recommended)

The quickest way to run K9db is to pull the pre-built image from Docker Hub. It is multi-arch, so docker automatically pulls the variant matching your machine:

docker pull kinanbab/k9db:latest
docker run -d --name k9db -p 10001:10001 -v k9db-data:/var/lib/k9db kinanbab/k9db:latest

K9db then accepts MySQL-compatible connections on port 10001:

mariadb --host=127.0.0.1 --port=10001

Note: not every MySQL client is compatible. MySQL clients version 9 and later cannot connect to K9db, and some clients need extra flags. See Tutorial for the details and for a dockerized client you can use without installing one.

The database is stored in the k9db-data docker volume, so it persists across containers (e.g. when upgrading the image). Arguments passed after the image name replace the default flags (--hostname=0.0.0.0:10001 --db_path=/var/lib/k9db/).

Starting from a fresh database

Because the database lives in the k9db-data volume, deleting the container is not enough to reset it: you must remove the volume too.

docker stop k9db
docker rm k9db
docker volume rm k9db-data
docker run -d --name k9db -p 10001:10001 -v k9db-data:/var/lib/k9db kinanbab/k9db:latest

Building the release image from source

If you want to build the image yourself (e.g. to run modified code), the release image builds K9db from source in an intermediate stage and only ships the compiled server and its runtime dependencies:

cd <K9DB_DIR>  # navigate to repo root directory
docker build -f Dockerfile.release -t k9db .
docker run -d --name k9db -p 10001:10001 -v k9db-data:/var/lib/k9db k9db

Everything above about ports, the k9db-data volume, and starting from a fresh database applies to this image too.

Note: building the image compiles K9db and its dependencies, which may take a while (30+ minutes) and requires several GBs of memory. If the build fails with out-of-memory errors and you are on Docker Desktop, increase the memory limit in its settings (Settings > Resources).

Dev image: building K9db and running tests and experiments

The dev image contains all build and experiment dependencies (bazel, gcc, rust, mariadb, memcached, latex, etc.). It does not contain the repo itself: the repo is bind-mounted into the container, so changes you make to the repo on your host are visible inside the container and vice-versa.

cd <K9DB_DIR>  # navigate to repo root directory
docker build -f Dockerfile.dev -t k9db/dev .
docker run --mount type=bind,source=$(pwd),target=/home/k9db --name k9db-dev -d -p 3306:3306 -p 10001:10001 -t k9db/dev

The same Dockerfile.dev works on both x86_64 and arm64 machines: the only architecture-dependent step is the bazel install, which the Dockerfile selects automatically using docker's TARGETARCH.

Note: K9db does not build under emulation, so the container must run natively. This is the default, but if you have set DOCKER_DEFAULT_PLATFORM=linux/amd64 (or otherwise configured docker to default to x86_64), unset it or pass --platform linux/arm64 explicitly when building and running on an arm64 machine.

No configuration is needed on startup: the bazel BUILD files for rust dependencies are vendored in the repo (see Building, Testing, and Running for re-vendoring them after changing rust dependencies), and mariadb (used by the experiment baselines) is configured when the image is built.

You can open a terminal inside the container:

docker exec -it k9db-dev /bin/bash
$ # now you are inside the container
$ cd /home/k9db
$ ls  # you should see the contents of this repo
$ bazel build :k9db  # build K9db (see Building, Testing, and Running)
$ exit  # exit the container when you are done.

You can stop the container and restart it as you wish using:

docker stop k9db-dev
docker start k9db-dev