Installation¶

This guide covers all methods for installing Uni, from building from source to using pre-built binaries.

System Requirements¶

Minimum Requirements¶

Component	Requirement
OS	Linux (x86_64, aarch64), macOS (x86_64, Apple Silicon)
Memory	4 GB RAM minimum, 16 GB recommended for large graphs
Disk	SSD recommended for optimal performance
Rust	1.75+ (if building from source)

Build Dependencies¶

Building Uni requires several system dependencies:

Dependency	Purpose	Installation
Rust toolchain	Compilation	rustup.rs
Clang/LLVM	Lance native dependencies	System package manager
Protocol Buffers	Lance serialization	System package manager
pkg-config	Build configuration	System package manager
OpenSSL	TLS for object store access	System package manager

Installation Methods¶

Method 1: Build from Source (Recommended)¶

Building from source provides the latest features and allows customization.

Step 1: Install Rust¶

# Install rustup (Rust toolchain manager)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Reload your shell configuration
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

Step 2: Install System Dependencies¶

Ubuntu / Debian:

sudo apt update
sudo apt install -y \
    build-essential \
    pkg-config \
    libssl-dev \
    protobuf-compiler \
    clang \
    llvm

Fedora / RHEL:

sudo dnf install -y \
    gcc \
    gcc-c++ \
    pkg-config \
    openssl-devel \
    protobuf-compiler \
    clang \
    llvm

macOS:

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install protobuf llvm pkg-config openssl@3

# Add LLVM to PATH (for Apple Silicon)
echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Arch Linux:

sudo pacman -S base-devel pkg-config openssl protobuf clang llvm

Step 3: Clone and Build¶

# Clone the repository
git clone https://github.com/dragonscale/uni.git
cd uni

# Build in release mode (optimized)
cargo build --release

# The binary is now at target/release/uni
ls -la target/release/uni

Step 4: Install to PATH (Optional)¶

# Option A: Copy to /usr/local/bin
sudo cp target/release/uni /usr/local/bin/

# Option B: Add cargo bin to PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
cargo install --path .

Method 2: Using Cargo Install¶

If you only need the CLI and don't require source modifications:

# Install directly from the repository
cargo install --git https://github.com/dragonscale/uni.git

# Or from crates.io (when published)
cargo install uni

Method 3: Docker¶

Run Uni in a containerized environment:

# Build the Docker image
docker build -t uni:latest .

# Run with local storage mounted
docker run -v $(pwd)/storage:/data uni:latest \
    query "MATCH (n) RETURN n LIMIT 10" --path /data

Docker Compose example:

version: '3.8'
services:
  uni:
    build: .
    volumes:
      - ./storage:/data
      - ./schema.json:/app/schema.json
    environment:
      - UNI_STORAGE_PATH=/data
      - RUST_LOG=info

Verification¶

After installation, verify Uni is working correctly:

Check Version¶

uni --version
# Output: uni 0.1.0

Display Help¶

uni --help

Expected output:

Uni - The Embedded Multi-Model Graph Database

Usage: uni <COMMAND>

Commands:
  import  Import data from JSONL files
  query   Execute a Cypher query
  start   Start the HTTP server
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Run a Simple Query¶

# Create a test directory
mkdir -p /tmp/uni-test

# Run a query (will create empty storage)
uni query "RETURN 1 + 1 AS result" --path /tmp/uni-test

# Expected output:
# ┌────────┐
# │ result │
# ├────────┤
# │ 2      │
# └────────┘

Troubleshooting Installation¶

Common Issues¶

"protoc not found"¶

# Ubuntu/Debian
sudo apt install protobuf-compiler

# macOS
brew install protobuf

# Verify
protoc --version

"failed to run custom build command for `ring`"¶

This usually indicates missing C compiler or LLVM:

# Ubuntu/Debian
sudo apt install build-essential clang

# macOS
xcode-select --install

"openssl not found"¶

# Ubuntu/Debian
sudo apt install libssl-dev pkg-config

# macOS
brew install openssl@3
export OPENSSL_DIR=$(brew --prefix openssl@3)

Slow Compilation¶

Enable parallel compilation and use the mold linker:

# Install mold (Linux)
sudo apt install mold

# Configure Cargo to use mold
cat >> ~/.cargo/config.toml << EOF
[target.x86_64-unknown-linux-gnu]
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=mold"]
EOF

# Rebuild
cargo build --release

Feature Flags¶

Uni supports optional features that can be enabled during compilation:

Feature	Description	Default
`fastembed`	Local embedding model support	Enabled
`s3`	Amazon S3 object store	Enabled
`gcs`	Google Cloud Storage	Disabled
`azure`	Azure Blob Storage	Disabled

Custom Build Example¶

# Minimal build (local filesystem only)
cargo build --release --no-default-features

# Build with all cloud providers
cargo build --release --features "s3,gcs,azure"

# Build without embedding support (smaller binary)
cargo build --release --no-default-features --features "s3"

Development Setup¶

For contributing to Uni, set up the full development environment:

# Clone with submodules
git clone --recursive https://github.com/dragonscale/uni.git
cd uni

# Install development tools
cargo install cargo-watch cargo-nextest

# Run tests
cargo nextest run

# Run with hot-reload during development
cargo watch -x "run -- query 'RETURN 1'"

# Check code quality
cargo fmt --check
cargo clippy -- -D warnings

Next Steps¶

Now that Uni is installed:

Quick Start — Import data and run your first queries
CLI Reference — Learn all available commands
Data Model — Understand vertices, edges, and properties