Installation Guide¶
This guide covers all installation methods for KotaDB, from quick setup to production deployments.
System Requirements¶
Minimum Requirements¶
- CPU: 2 cores
- RAM: 512MB
- Disk: 100MB for binaries + data storage
- OS: Linux, macOS, or Windows
Recommended Requirements¶
- CPU: 4+ cores
- RAM: 2GB+
- Disk: SSD with 10GB+ free space
- OS: Linux (Ubuntu 22.04+ or similar)
Installation Methods¶
1. Build from Source¶
Prerequisites¶
- Rust 1.75.0+ (Install Rust)
- Git
- C compiler (gcc/clang)
Steps¶
# Clone the repository
git clone https://github.com/jayminwest/kota-db.git
cd kota-db
# Build in release mode
cargo build --release
# The binary will be at ./target/release/kotadb
./target/release/kotadb --version
Development Build¶
For development with debug symbols and faster compilation:
2. Docker Installation¶
Using Docker Hub¶
# Pull the latest image
docker pull kotadb/kotadb:latest
# Run with default configuration
docker run -d \
--name kotadb \
-p 8080:8080 \
-v $(pwd)/data:/data \
kotadb/kotadb:latest
Building Docker Image Locally¶
# Build the image
docker build -t kotadb:local .
# Run the locally built image
docker run -d \
--name kotadb \
-p 8080:8080 \
-v $(pwd)/data:/data \
kotadb:local
3. Using Cargo Install¶
# Install directly from crates.io (when published)
cargo install kotadb
# Or install from GitHub
cargo install --git https://github.com/jayminwest/kota-db.git
4. Pre-built Binaries¶
Download pre-built binaries from the GitHub Releases page:
# Linux x86_64
wget https://github.com/jayminwest/kota-db/releases/latest/download/kotadb-linux-x86_64.tar.gz
tar -xzf kotadb-linux-x86_64.tar.gz
sudo mv kotadb /usr/local/bin/
# macOS
wget https://github.com/jayminwest/kota-db/releases/latest/download/kotadb-darwin-x86_64.tar.gz
tar -xzf kotadb-darwin-x86_64.tar.gz
sudo mv kotadb /usr/local/bin/
# Windows
# Download kotadb-windows-x86_64.zip from releases page
# Extract and add to PATH
Platform-Specific Instructions¶
Linux¶
Ubuntu/Debian¶
# Install build dependencies
sudo apt-get update
sudo apt-get install -y build-essential git curl
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
# Build KotaDB
git clone https://github.com/jayminwest/kota-db.git
cd kota-db
cargo build --release
Fedora/RHEL¶
# Install build dependencies
sudo dnf install -y gcc git curl
# Install Rust and build (same as Ubuntu)
Arch Linux¶
# Install from AUR (when available)
yay -S kotadb
# Or build manually
sudo pacman -S base-devel git rust
git clone https://github.com/jayminwest/kota-db.git
cd kota-db
cargo build --release
macOS¶
# Install Xcode Command Line Tools
xcode-select --install
# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Rust
brew install rust
# Build KotaDB
git clone https://github.com/jayminwest/kota-db.git
cd kota-db
cargo build --release
Windows¶
Using WSL2 (Recommended)¶
Native Windows¶
# Install Rust (download from https://rustup.rs)
# Install Git for Windows
# Install Visual Studio Build Tools
# Clone and build
git clone https://github.com/jayminwest/kota-db.git
cd kota-db
cargo build --release
Client Libraries¶
Python Client¶
# Install from PyPI
pip install kotadb-client
# Or install from source
git clone https://github.com/jayminwest/kota-db.git
cd kota-db/clients/python
pip install -e .
TypeScript/JavaScript Client¶
# Install from npm
npm install kotadb-client
# Or using yarn
yarn add kotadb-client
# Or install from source
git clone https://github.com/jayminwest/kota-db.git
cd kota-db/clients/typescript
npm install
npm run build
Verification¶
After installation, verify KotaDB is working:
# Check version
kotadb --version
# Run tests
cargo test --lib
# Start with default configuration
kotadb --config kotadb-dev.toml
# Check server health
curl http://localhost:8080/health
Development Setup¶
For contributors and developers:
# Install development dependencies
cargo install just
cargo install cargo-watch
cargo install cargo-audit
cargo install cargo-tarpaulin
# Setup pre-commit hooks
just setup-dev
# Run development server with auto-reload
just dev
# Run all checks before committing
just check
Client Libraries¶
Python Client¶
TypeScript/JavaScript Client¶
Rust Client¶
Add to your Cargo.toml
:
Configuration¶
Create a configuration file kotadb.toml
:
[storage]
path = "./data"
cache_size = 1000
[server]
host = "0.0.0.0"
port = 8080
[logging]
level = "info"
See Configuration Guide for all options.
Troubleshooting¶
Common Issues¶
Port Already in Use¶
# Find process using port 8080
lsof -i :8080 # Linux/macOS
netstat -ano | findstr :8080 # Windows
# Use a different port
kotadb --port 8081
Permission Denied¶
Build Failures¶
# Clean build cache
cargo clean
# Update Rust
rustup update
# Try building with verbose output
cargo build --release --verbose
Next Steps¶
- Configuration Guide - Customize your setup
- First Database - Create your first database
- Basic Operations - Learn CRUD operations
- API Reference - Explore the APIs