Setup Guide

Prerequisites

Before installing ShibuDB, ensure your system meets the following requirements:

System Requirements

Operating System: Linux (AMD64/ARM64) or macOS (Apple Silicon)
Go Version: 1.23.0 or later (for source builds)
Memory: Minimum 512MB RAM, recommended 2GB+
Disk Space: Minimum 1GB free space
Network: TCP port access for client connections

Dependencies

FAISS Libraries: Included in the package
System Libraries: Standard C libraries
Homebrew: Optional (for macOS installation)

Installation

Choose the installation method that best fits your environment:

macOS Installation

Apple Silicon

# Download and install
# Option A: download from the latest GitHub release page
open https://github.com/shibudb-org/shibudb-server/releases/latest

# Option B: download the latest release asset via GitHub CLI (recommended for scripting)
# (install `gh` first: https://cli.github.com/)
gh release download --repo shibudb-org/shibudb-server --pattern "*apple_silicon.pkg" --clobber
sudo installer -pkg ./*.pkg -target /

# Verify installation
shibudb --version

Using Homebrew

# Add ShibuDB tap
brew tap shibudb-org/shibudb

# Install ShibuDB
brew install shibudb

# Link if upgrading
brew link shibudb

Linux Installation

Pre-built packages are the fastest option for current Linux distributions such as Debian 12, Ubuntu 22.04 or newer, Rocky/AlmaLinux 9, Amazon Linux 2023, and Fedora. If a package is not compatible with your distribution, use the source installer below.

Debian/Ubuntu (AMD64)

# Download and install
gh release download --repo shibudb-org/shibudb-server --pattern "*amd64.deb" --clobber
sudo dpkg -i ./*.deb

Debian/Ubuntu (ARM64)

# Download and install
gh release download --repo shibudb-org/shibudb-server --pattern "*arm64.deb" --clobber
sudo dpkg -i ./*.deb

RHEL/CentOS/Fedora (AMD64)

# Download and install
gh release download --repo shibudb-org/shibudb-server --pattern "*x86_64.rpm" --clobber
sudo rpm -i ./*.rpm

RHEL/CentOS/Fedora (ARM64)

# Download and install
gh release download --repo shibudb-org/shibudb-server --pattern "*aarch64.rpm" --clobber
sudo rpm -i ./*.rpm

Linux Source Installer

Use the source installer for older Linux distributions, minimal server images, or any Linux system where the pre-built package is not compatible. It builds the shibudb binary on the target machine while using the bundled FAISS libraries from the ShibuDB source tree.

The installer supports Linux amd64 and arm64. It can install dependencies through apt, dnf, or yum, and downloads a temporary Go toolchain if Go 1.23 or later is not already installed.

Install from Source

# Install the latest release
curl -fsSL https://raw.githubusercontent.com/shibudb-org/shibudb-server/main/scripts/install-linux.sh | bash

# Install a specific release
curl -fsSL https://raw.githubusercontent.com/shibudb-org/shibudb-server/main/scripts/install-linux.sh | bash -s -- --version {version}

The source installer installs the ShibuDB binary, FAISS libraries, and shared resources:

Installed Paths

/usr/local/bin/shibudb
/usr/local/lib/libfaiss.so
/usr/local/lib/libfaiss_c.so
/usr/local/share/shibudb/

Optional Source Installer Flags

# Install to a custom prefix
curl -fsSL https://raw.githubusercontent.com/shibudb-org/shibudb-server/main/scripts/install-linux.sh | bash -s -- --prefix /opt/shibudb

# Build from an existing checkout
./scripts/install-linux.sh --source /path/to/shibudb-server

# If dependencies are already installed
./scripts/install-linux.sh --skip-deps

Initial Configuration

ShibuDB automatically creates the required directory structure and can be configured for your needs:

Directory Structure

ShibuDB automatically creates the following directory structure:

Default Directories

~/.shibudb/lib/             # Database + config files
~/.shibudb/log/shibudb.log  # Log file
~/.shibudb/run/shibudb.pid  # PID file

Connection Limits

By default, ShibuDB allows up to 1000 concurrent connections. You can modify this:

Connection Configuration

# Start with custom connection limit
sudo shibudb start 9090 2000

# Or update at runtime
shibudb manager 9090 limit 2000

First Steps

Now let's start ShibuDB and verify it's working correctly:

1. Start the Server

Start Server

# Start with default settings (port 9090, 1000 connections)
# First time start will ask for new admin credentials
shibudb start 9090

# Start with admin credentials (non-interactive)
shibudb start --admin-user admin --admin-password admin 9090

# Start with custom connection limit
shibudb start 9090 500

2. Connect to the Database

Connect

# Connect to the server (will prompt for credentials)
shibudb connect 9090

# You'll be prompted for credentials:
Username: {admin username}
Password: {admin password}

# Connect with credentials (non-interactive)
shibudb connect --admin-user admin --admin-password admin 9090

3. Create Your First Space

Create Space

# Create a key-value space
CREATE-SPACE my_data --engine key-value

# Create a vector space for similarity search
CREATE-SPACE my_vectors --engine vector --dimension 128 --index-type Flat --metric L2

4. Basic Operations

Basic Operations

# Use the space
USE my_data

# Store and retrieve data
PUT user:1 "John Doe"
GET user:1
DELETE user:1

# Vector operations (in vector space)
USE my_vectors
INSERT-VECTOR 1 1.0,2.0,3.0,4.0
SEARCH-TOPK 1.1,2.1,3.1,4.1 5
RANGE-SEARCH 1.0,2.0,3.0,4.0 0.5

Verification

Verify that ShibuDB is running correctly:

1. Check Server Status

Server Status

# Check if server is running
ps aux | grep shibudb

# Check server logs
tail -f ~/.shibudb/log/shibudb.log

2. Test Connection

Connection Test

# Test basic connectivity
telnet localhost 9090

# Test management API
curl http://localhost:10090/health

3. Verify Management API

Management API

# Get connection statistics
curl http://localhost:10090/stats

# Get current connection limit
curl http://localhost:10090/limit

Next Steps

After successful setup, explore these guides:

Key-Value Engine

Master key-value operations and storage

Learn More

Vector Engine

Explore vector search capabilities

Explore

Table of Contents