Skip to main content

Install from Binary

Download and unzip EloqKV tarball​

EloqKV on EloqStore requires Ubuntu 24.04. Download tarball.

After successfully downloading the proper binary, untar it in a directory.

cd ${HOME}
tar -zxvf eloqkv-1.2.0-ubuntu24-amd64.tar.gz

System Configuration​

To ensure EloqKV runs optimally, update /etc/security/limits.conf with the following settings to increase open file limits and memory lock capabilities:

* soft nofile 524288
* hard nofile 524288
* soft core unlimited
* hard core unlimited
* soft memlock unlimited
* hard memlock unlimited

After saving your changes, log out and log back in (or reboot the server) for the updated limits to take effect.

Prepare EloqKV config file​

EloqKV uses a configuration file to customize settings. An example is provided in conf/eloqkv.ini under the installation directory. EloqKV will automatically set reasonable default values for its parameters if no user specified value is provided in the configuration file. Check configuration for advanced setting.

Below is an example of how to configure EloqKV to run on a local machine.

[local]
# It is recommended to set the IP to the actual server IP for external access
ip=127.0.0.1
port=6379

[store]
# It is recommended to set eloq_store_data_path_list to NVMe SSD.
# Shard data directories separated by ',' when multiple. By default under eloq_data_path.
# eloq_store_data_path_list=

Start EloqKV server​

The EloqKV eloqkv executable binary is installed in the EloqKV/bin directory. Start the server on the local machine using the commands below.

cd ${HOME}/EloqKV
./bin/eloqkv --config=conf/eloqkv.ini

Connect to EloqKV server​

EloqKV is compatible with the Redis protocol. We have included a eloq-cli for your convinence, but any redis client can connect to EloqKV. You can obtain official redis-cli by e.g. execute sudo apt-get install redis-tools on Ubuntu. Please use the same ip and port in config file eloqkv.ini to connect to EloqKV.

redis-cli -h 127.0.0.1 -p 6379

Enable Persistent Data Store​

EloqKV supports the integration with pluggable data stores, enabling data persistence even when the EloqKV service is stopped. This capability facilitates the implementation of tiered storage strategies, allowing hot data to reside in memory for quick access, while cold data can be offloaded to disks.

[local]
# set it to `on` to turn on persistent storage. Default value: 'on'
enable_data_store=on

# Checkpoint_interval determines the period of flushing records into persistent store
# so that data in persistent store will not lag too much behind. Default value: 10
checkpointer_interval=10

Enable WAL for Durability​

By enabling the Write-Ahead Logging (WAL), EloqKV can achieve Durability, i.e. all writes will be logged and data won't get lost in the event of a system crash. WAL need to be combined with persistent data store to work properly.

Edit eloqkv.ini and restart EloqKV to enable WAL.

[local]
# set it to `on` to turn on WAL
enable_wal=on

Setting Up an EloqKV Cluster with MinIO (Cloud Object Storage)​

To set up a EloqKV cluster that uses MinIO (or S3-compatible) object storage for persistence and durability, follow these steps:

1. Start the MinIO Server​

First, deploy a MinIO server to provide S3-compatible object storage. The following example runs MinIO locally on server 192.168.1.23 (adjust the IP as needed):

# Download and make MinIO executable
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio

# Start the MinIO server (default port: 9000)
./minio server /tmp/minio-data

Make sure to configure MinIO with your desired access credentials and note the endpoint URL (e.g., http://192.168.1.23:9000).

2. Prepare EloqKV Node Configuration​

Suppose you want to run a three-node cluster (on hosts 192.168.1.20, 192.168.1.21, 192.168.1.22). On each node, create or update the eloqkv.ini file with the appropriate settings. Below is an example configuration for the node at 192.168.1.20:

[local]
# Local IP address of the EloqKV node. This value is recorded in the EloqKV catalog and
# cannot be changed once the server has been launched. It is strongly recommended to set
# this to the actual IP address of the node.
ip = 192.168.1.20

[cluster]
# ip_port_list should include all eloqkv nodes in the cluster.
# Make sure to set them to match the ip:port specified in the [local]
# section of the configuration file on each node.
ip_port_list=192.168.1.20:6379,192.168.1.21:6379,192.168.1.22:6379

# node_group_replica_num should always set to 1 when enable eloqstore.
node_group_replica_num=1

# [CLOUD REQUIRED] Cloud storage URI used for remote persistence.
# Can be bucket_name or bucket_name/path; if empty, EloqKV stays in local mode.
eloq_store_cloud_store_path=miniotest

# [CLOUD REQUIRED] Endpoint of the object storage service
# (e.g. http://127.0.0.1:9000 for MinIO, https://s3.<region>.amazonaws.com for S3,
# https://storage.googleapis.com for GCS).
eloq_store_cloud_endpoint=http://192.168.1.23:9000

# [CLOUD REQUIRED] Cloud access key id.
eloq_store_cloud_access_key=minioadmin

# [CLOUD REQUIRED] Cloud secret key paired with the access key.
eloq_store_cloud_secret_key=minioadmin

# [CLOUD OPTIONAL] Warm the cloud cache on startup for hot data.
eloq_store_prewarm_cloud_cache=true

# [CLOUD OPTIONAL] Reuse existing local files when restoring from cloud.
eloq_store_reuse_local_files=true

First, initialize (bootstrap) the cluster:

./bin/eloqkv --config conf/eloqkv.ini --bootstrap

Then, start each of the three nodes individually:

./bin/eloqkv --config conf/eloqkv.ini

Now you can connect your client to any one of the servers in the cluster and enjoy the increased capacity. Data will be automatically sharded.

Note that Distributed transactions are supported in EloqKV clusters. For example, MULTI commands and Lua scritpts will behave the same in a cluster just as on a single node. To enable this feature, you need to enable auto-redirect.

[local]
auto_redirect=true