valkey-setup

A utility for creating a customized, rootless Valkey container image with the option of including compiled modules (extensions) like JSON, Search, and Bloom filters.

Base Image: openSUSE Leap 16.0
Valkey Version: 9.0.1 (Compiled from source)

Pre-requisites

OS: Linux-based.

Required Tools

Package	Version	Notes
Python	3.13+	Core language the CLI tool is written in.
Poetry	2.2.1+	Project dependency manager.
Buildah	1.41.5+	Used to programmatically create OCI-compliant container images without a daemon.
Taskfile	3.46.3+	Optional. You can use the provided shell script wrapper (./taskw) which scopes the binary to the project.

Usage

List available tasks:

./taskw --list

Setup python virtual environment and install dependencies:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY deps

View CLI tool options and build help:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- --help

Example

Build valkey core binary from source:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- containers core build

Build specific modules:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- containers modules valkey-json build

Build valkey runtime including the modules:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- containers runtime build --modules valkey-json,valkey-search,valkey-bloom

Run built container using podman:

#!/bin/bash

CONTAINER="valkey9.0.1"
NETWORK="tumbleweed"
NETWORK_ALIAS="valkey9.0.1"
CONTAINER_UID=999
CONTAINER_GID=999
HOST_PORT=6379
VOLUME="valkey"
IMAGE="localhost/valkey:9.0.1"

podman volume exists $VOLUME || podman volume create $VOLUME

podman unshare chown -R $CONTAINER_UID:$CONTAINER_GID $(podman volume inspect $VOLUME --format '{{.Mountpoint}}')

podman run -d \
        --name $CONTAINER \
        --network $NETWORK \
        --network-alias $NETWORK_ALIAS \
        --user $CONTAINER_UID:$CONTAINER_GID \
        -p $HOST_PORT:6379 \
        -v $VOLUME:/var/lib/valkey/data \
        $IMAGE

Application Container Image Features

Modules

Valkey supports a dynamic module system that extends its core capabilities. This CLI tool compiles these modules from source and integrates them into the runtime image.

JSON Document Store

Module	Version	Description
valkey-json	1.0.2	Adds native JSON support. Provides JSON.SET, JSON.GET, and standard JSONPath syntax for deep access/modification.

Search & Vectors

Module	Version	Description
valkey-search	1.1.0	Secondary indexing, full-text search, and vector similarity search. Supports HNSW and Flat vector indexing for AI/LLM workloads. Automatically indexes data stored via valkey-json.

Probabilistic Data Structures

Module	Version	Description
valkey-bloom	1.0.0	High-performance probabilistic data structures. Bloom Filter: High-speed set membership checks with zero false negatives. Cuckoo Filter: Similar to Bloom but supports deletion. Count-Min Sketch: Memory-efficient frequency counting.

Ports

Port	Purpose
6379	Default Valkey Port. Map this to your host using -p 6379:6379.

Volumes

Path	Purpose
/var/lib/valkey/data	Data Directory. Stores the persistence files (dump.rdb and appendonly.aof). Note: Ensure you mount a volume here to prevent data loss on restart.