How to Build and Compile VelesDB from Source: Complete Installation Guide

To build VelesDB from source, install Rust 1.83+, clone the cyberlife-coder/velesdb repository, and run cargo build --release to compile the workspace; binaries appear in target/release/ including velesdb-server and velesdb-cli.

VelesDB is a Rust-first, multi-model database distributed as a Cargo workspace containing multiple specialized crates. Building and compiling VelesDB from source requires the Rust toolchain and standard Cargo workflows, whether you need the full server binary, core library, or language-specific bindings.

Prerequisites for Building VelesDB from Source

Rust Toolchain Requirements

The workspace pins the Rust version via rust-toolchain.toml (nightly-2024-09-15). You need Rust 1.83 or higher to compile VelesDB from source.

curl https://sh.rustup.rs -sSf | sh
rustup show  # Auto-selects the pinned nightly toolchain

Cargo installs automatically with Rust. Running rustup show in the repository root selects the exact nightly version specified in the workspace configuration.

Optional System Dependencies

While not strictly required, installing Clang/LLVM enables native-CPU SIMD optimizations in the core engine:

# Ubuntu/Debian

apt-get install clang

# macOS

brew install llvm

For containerized builds, Docker 20.x or later supports the multi-stage Dockerfile provided in the repository root.

Clone the VelesDB Repository

Clone the official repository and enter the workspace directory:

git clone https://github.com/cyberlife-coder/velesdb.git
cd velesdb

The repository root contains the workspace Cargo.toml defining shared dependencies (Tokio, Axum, Serde) across all crates, as documented in the installation guide at docs/guides/INSTALLATION.md.

Compile the Workspace (Full Build)

Build All Crates in Release Mode

To compile every workspace member—including velesdb-core, velesdb-server, velesdb-cli, and velesdb-wasm—execute the release build:

cargo build --release

This places optimized binaries under target/release/, including the velesdb-server HTTP API and the velesdb-cli interactive REPL.

Build Individual Components

Use the -p flag to build specific crates without compiling the entire workspace:

• Core library only: cargo build -p velesdb-core --release
• Server binary: cargo build -p velesdb-server --release
• CLI REPL: cargo build -p velesdb-cli --release
• WASM module: cargo build -p velesdb-wasm --release --target wasm32-unknown-unknown

These commands correspond to the build instructions in docs/guides/INSTALLATION.md (lines 55-67), allowing targeted compilation when you only need specific functionality.

Platform-Specific Build Instructions

Build the VelesDB Server Binary

The server binary wraps the core engine in an Axum-based HTTP REST API. After building, launch the server with a data directory:

cargo build -p velesdb-server --release
./target/release/velesdb-server --data-dir ./data --host 0.0.0.0 --port 8080

The server entry point at crates/velesdb-server/src/main.rs handles argument parsing and initializes the AppState containing the Database instance.

Build the CLI REPL

The interactive REPL provides direct VelesQL access to the core engine:

cargo build -p velesdb-cli --release
./target/release/velesdb-cli repl

This binary links against velesdb-core to instantiate the Database abstraction used across all interfaces.

Build WebAssembly (WASM) Bindings

For browser or Node.js environments, compile the WASM target:

rustup target add wasm32-unknown-unknown
cargo build -p velesdb-wasm --release --target wasm32-unknown-unknown

The output file target/wasm32-unknown-unknown/release/velesdb_wasm.wasm is packaged as the @wiscale/velesdb-wasm npm module.

Build Python Bindings with PyO3

The velesdb-python crate uses PyO3 and maturin to generate native Python modules:

cd crates/velesdb-python
pip install maturin
maturin develop --release

After compilation, import velesdb works immediately in Python, exposing the same Database and collection APIs implemented in crates/velesdb-core/src/lib.rs.

Build Mobile Libraries (iOS and Android)

VelesDB supports mobile via UniFFI bindings in the velesdb-mobile crate.

iOS (ARM64):

rustup target add aarch64-apple-ios
cargo build --release --target aarch64-apple-ios -p velesdb-mobile

Android (ARM64 and ARMv7):

rustup target add aarch64-linux-android
cargo install cargo-ndk
cargo ndk -t arm64-v8a -t armeabi-v7a build --release -p velesdb-mobile

These commands produce static libraries (.a for iOS) and shared libraries (.so for Android) with generated UniFFI bindings, as specified in docs/guides/INSTALLATION.md (lines 40-62).

Docker Build Process

For production deployments, build the container image using the repository's multi-stage Dockerfile:

docker build -t velesdb .
docker run -d -p 8080:8080 -v velesdb_data:/data velesdb

The Dockerfile compiles velesdb-server in release mode and copies the binary into a minimal runtime image, defaulting to port 8080 with the data directory mounted at /data.

Verify Your Build

Confirm successful compilation by starting the server and checking the binary version:

./target/release/velesdb-server --version
./target/release/velesdb-server --data-dir ./test_data &
curl http://localhost:8080/health

A successful response indicates the Axum server initialized correctly from crates/velesdb-server/src/main.rs and is serving the REST API endpoints defined in the core routing logic.

Summary

• Install Rust 1.83+ and run rustup show to select the nightly-2024-09-15 toolchain pinned in the workspace.
• Clone the cyberlife-coder/velesdb repository and use cargo build --release for full workspace compilation.
• Target specific crates with -p velesdb-server, -p velesdb-cli, or -p velesdb-wasm to avoid building unnecessary components.
• Build language bindings using maturin for Python, wasm32-unknown-unknown target for browsers, and cargo-ndk for Android.
• Deploy using the provided Dockerfile or run binaries directly from target/release/.

Frequently Asked Questions

What Rust version is required to compile VelesDB?

VelesDB requires Rust 1.83 or higher, though the workspace pins a specific nightly toolchain (nightly-2024-09-15) via rust-toolchain.toml. Running rustup show automatically installs and selects this version, ensuring SIMD optimizations and workspace dependencies compile correctly.

How do I build only the VelesDB server without other crates?

Use the package-specific flag: cargo build -p velesdb-server --release. This skips the WASM, Python, and mobile crates, producing only the velesdb-server binary in target/release/. The server depends only on velesdb-core, so this build completes significantly faster than the full workspace.

Can I compile VelesDB on Windows?

Yes. The build commands are identical across Linux, macOS, and Windows. Windows users should install the MSVC toolchain via Visual Studio Build Tools rather than GCC, as the core engine's SIMD optimizations rely on LLVM/Clang compatibility layers that work best with the Microsoft C++ toolchain on Windows.

How do I build VelesDB for production deployment?

For production, always use --release mode for optimizations, and consider the Docker build for consistent deployment. The Dockerfile at the repository root performs a multi-stage build that compiles the server in release mode and packages it with minimal dependencies, exposing port 8080 for the REST API and supporting volume mounts for persistent data storage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}