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

> Learn to build and compile VelesDB from source with this complete installation guide. Follow simple steps to get the VelesDB binaries ready for use.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/cyberlife-coder/velesdb/blob/main/rust-toolchain.toml) (nightly-2024-09-15). You need **Rust 1.83 or higher** to compile VelesDB from source.

```bash
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:

```bash

# 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:

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

```

The repository root contains the workspace [`Cargo.toml`](https://github.com/cyberlife-coder/velesdb/blob/main/Cargo.toml) defining shared dependencies (Tokio, Axum, Serde) across all crates, as documented in the installation guide at [`docs/guides/INSTALLATION.md`](https://github.com/cyberlife-coder/velesdb/blob/main/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:

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/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:

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/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):**

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

```

**Android (ARM64 and ARMv7):**

```bash
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`](https://github.com/cyberlife-coder/velesdb/blob/main/docs/guides/INSTALLATION.md) (lines 40-62).

## Docker Build Process

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

```bash
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:

```bash
./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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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.