Installation¶

This guide covers all installation methods for Alopex DB.

System Requirements¶

Installation Methods¶

As a Library (Embedded Mode)¶

Add Alopex to your Rust project:

[dependencies]
alopex-embedded = "0.4"
alopex-sql = "0.4"

cargo add alopex-embedded alopex-sql

From Source¶

Clone and build from source:

# Clone the repository
git clone https://github.com/alopex-db/alopex.git
cd alopex

# Build all crates
cargo build --release

# Run tests
cargo test

# Install CLI tools (optional)
cargo install --path alopex-cli

CLI (Optional)¶

The CLI defaults to the TUI on TTY terminals. Force batch output with --batch or an explicit --output format. In the results TUI, press a to open the admin console when available. The status bar emphasizes Connection/Focus/Action and Ops so you can see the current target and primary actions at a glance. Run alopex (no subcommand) or alopex server to open the admin console; lifecycle actions (archive/restore/backup/export) live in the Actions list and require server permissions. The admin console uses a rainfrog-style layout (left resource tree, right detail input, right-bottom status/preview) with h/l focus switching.

Feature Flags¶

Feature	Description	Default
hnsw	Enable HNSW vector indexing
compression	Enable data compression
metrics	Prometheus metrics export
tracing	Distributed tracing support

[dependencies]
alopex-embedded = { version = "0.4", features = ["hnsw", "metrics"] }
alopex-sql = "0.4"

Platform-Specific Notes¶

Linux¶

No additional dependencies required. For optimal performance:

# Increase file descriptor limits
ulimit -n 65536

# Enable huge pages (optional, for large datasets)
sudo sysctl -w vm.nr_hugepages=1024

macOS¶

Works out of the box with Xcode Command Line Tools:

xcode-select --install

Windows¶

Requires Visual Studio Build Tools:

1. Download Visual Studio Build Tools
2. Install "Desktop development with C++"
3. Restart terminal and build

WebAssembly¶

For browser deployments:

# Install wasm-pack
cargo install wasm-pack

# Build for WASM
wasm-pack build --target web alopex-wasm

Verifying Installation¶

# Check version
alopex --version

# Run a quick interactive query (TUI opens on TTY)
alopex --data-dir ./data sql "SELECT 1"

# Quick benchmark
alopex bench --quick

Troubleshooting¶

cargo build --release -j 2

# Data directory needs write access
chmod 755 /path/to/data

Next Steps¶

• Quick Start Guide
• Configuration Reference