Install With Docker Compose

Before You Start

Install Docker with Compose v2. Reserve at least 4 GiB for the Docker VM and several GiB of free disk space. Both Linux AMD64 and ARM64 images are available. The cluster image eloqdata/lavik:0.1.0-beta.1-cluster contains Data, Meta, lavik-ctl, redis-cli, and the bootstrap helper, using the Minimal release with kernel TCP and io_uring. It does not include SPDK/DPDK or Lavik Admin.

This is a local evaluation cluster on one Docker host, not protection against host failure. It uses beta.1’s NuRaft Meta implementation. Start with fresh volumes; do not reuse volumes from the newer source-built Admin quick start. All 16,384 slots initially belong to one primary, with native replication to its follower. Meta manages their roles.

The fixed bridge subnet 172.30.92.0/24 must be unused. Run only one copy of this example per Docker daemon. If necessary, change the addresses consistently in both compose.yaml and cluster.toml before the first startup. The containers run as UID/GID 10001:10001; seccomp=unconfined allows io_uring without privileged mode.

Download and Start the Cluster

Download the matching Compose file and manifest into a new directory. These links pin the dockerimages branch snapshot for beta.1; no repository clone or build is needed. Keep both files together, and run all subsequent Compose commands from this directory.

The initial primary publishes localhost:6379 and the initial follower localhost:6380. If occupied, run export LAVIK_PRIMARY_PORT=16779 LAVIK_FOLLOWER_PORT=16780 before the commands below and retain those settings for subsequent Compose commands. LAVIK_DATA_SIZE defaults to 1G per Data node and LAVIK_THREADS to 2.

mkdir -p lavik-compose
cd lavik-compose
curl --fail --location --output compose.yaml \
  https://raw.githubusercontent.com/eloqdata/lavik/a1770a78b52e0bb9ec32e20b92af6282e73efabd/deploy/docker/compose.yaml
curl --fail --location --output cluster.toml \
  https://raw.githubusercontent.com/eloqdata/lavik/a1770a78b52e0bb9ec32e20b92af6282e73efabd/deploy/docker/cluster.toml
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs -f bootstrap

Wait for “Cluster is READY (one primary, one follower).” and a successful bootstrap exit. Ctrl-C stops following the logs without stopping the containers. Per-container health checks only show process availability; use cluster-status to check cluster_ready and the current owner. If bootstrap fails, inspect docker compose logs bootstrap and cluster status before taking action; never delete volumes to repair uncertain state.

Connect and Check Replication

docker compose exec meta-1 lavik-ctl cluster-status \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin --json
docker compose exec primary redis-cli -c SET hello lavik
docker compose exec primary redis-cli -c GET hello

# Read on one connection after replication catches up.
printf 'READONLY\nGET hello\n' | docker compose exec -T follower redis-cli --raw

SET returns OK and GET returns lavik. The follower read sends READONLY and GET on the same connection; retry after replication catches up if the value has not arrived. The service names primary and follower describe initial roles, which can change.

The cluster advertises Docker-internal addresses. Cluster-aware clients that follow MOVED redirects must run on the Compose network; the exec commands above do so. On macOS, host clients can connect directly through published ports but cannot follow redirects to bridge addresses. A remote deployment needs addresses reachable by every node and client, plus authentication and TLS. This example publishes Data ports only on loopback, does not publish Meta ports, and uses plaintext inside the Docker network.

Try Controlled Failover

After the cluster is ready and replication has caught up, use the shipped lavik-ctl to transfer ownership of group-1. Inspect cluster-status afterward. redis-cli -c can follow the redirect from the old primary because it runs inside the Compose network.

docker compose exec meta-1 lavik-ctl failover group-1 \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin \
  --failover-timeout-ms 60000
docker compose exec meta-1 lavik-ctl cluster-status \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin --json
docker compose exec primary redis-cli -c GET hello

Stop and Recover the Cluster

docker compose down --timeout 60
docker compose up -d
docker compose logs -f bootstrap
# After bootstrap exits successfully, check readiness and the current owner.
docker compose exec meta-1 lavik-ctl cluster-status \
  --socket /data/meta/meta-admin.sock --allow-plaintext-admin --json
docker compose exec primary redis-cli -c GET hello

Each of the two Data nodes and three Meta nodes has its own named volume. docker compose down preserves these five volumes. On startup, Meta loads its durable topology; bootstrap initializes only an uninitialized cluster and otherwise waits for recovery. It does not reapply the original role assignments. Automatic failover during recovery can change the owner, so discover it with cluster-status rather than relying on service names.

Only for an intentional complete reset: docker compose down --volumes permanently deletes all five database volumes. Never add --volumes for a routine restart or upgrade. Changing LAVIK_DATA_SIZE does not resize existing files.

Manage a Primary–Follower Cluster and Set Up Grafana →