ThemisDB Development Environment Setup Guide

This guide covers setting up your development environment for ThemisDB with AI-Guardrails and modern tooling.

🎯 Quick Setup (Recommended)

Option 1: Dev Container (Fastest)

Prerequisites: Docker Desktop + VS Code with Remote Containers extension

# 1. Clone repository
git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB

# 2. Open in VS Code
code .

# 3. Reopen in Container
# Command Palette (Ctrl+Shift+P) → "Dev Containers: Reopen in Container"

# ✅ Environment is automatically configured!

Option 2: Local Setup

Prerequisites: Git, Python 3.8+, CMake 3.20+, C++ compiler

# 1. Clone repository
git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB

# 2. Install pre-commit hooks
# Windows
.\scripts\setup-pre-commit.ps1

# Linux/macOS
./scripts/setup-pre-commit.sh

# 3. Bootstrap third-party dependencies (vcpkg, ffmpeg, llama.cpp)
# Windows
.\scripts\setup-third-party.ps1

# Linux/macOS
pwsh ./scripts/setup-third-party.ps1

# 4. Configure VS Code (optional)
cp -r .vscode.example .vscode

# ✅ Ready to build!

📋 Detailed Setup Instructions

1. Prerequisites

All Platforms

Git - Version control
Python 3.8+ - For pre-commit hooks
CMake 3.20+ - Build system
vcpkg - Package manager (included in repo)

Windows

Visual Studio 2022 - C++ compiler
- Workload: "Desktop development with C++"
- Components: CMake tools, vcpkg
Windows SDK - Latest version

Linux

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
    build-essential \
    cmake \
    ninja-build \
    git \
    python3 \
    python3-pip \
    curl \
    zip \
    unzip

# Fedora/RHEL
sudo dnf install -y \
    gcc-c++ \
    cmake \
    ninja-build \
    git \
    python3 \
    python3-pip

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 dependencies
brew install cmake ninja python git

2. Clone Repository

git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB

3. Install Pre-commit Hooks

Pre-commit hooks automatically validate code before commits.

Windows

.\scripts\setup-pre-commit.ps1

Linux/macOS

./scripts/setup-pre-commit.sh

What this does:

Installs pre-commit tool
Configures git hooks
Sets up validation checks:
- Code formatting (clang-format)
- CMake linting
- Markdown linting
- Secret detection
- Copilot instruction validation

4. Configure third-party dependencies

ThemisDB uses vcpkg plus external components (ffmpeg, llama.cpp).

Windows

.\scripts\setup-third-party.ps1

Linux/macOS

pwsh ./scripts/setup-third-party.ps1

This ensures:

vcpkg/scripts/buildsystems/vcpkg.cmake is available
ffmpeg and llama.cpp submodules are initialized
vcpkg.json baseline commit is validated/fetched when possible

5. Configure VS Code (Optional but Recommended)

# Copy example configuration
cp -r .vscode.example .vscode

# Edit settings for your environment
code .vscode/settings.json

Install recommended extensions:

Open VS Code Command Palette (Ctrl+Shift+P)
Run: "Extensions: Show Recommended Extensions"
Click "Install All"

Key extensions:

C/C++ (ms-vscode.cpptools)
CMake Tools (ms-vscode.cmake-tools)
GitHub Copilot (github.copilot)
Remote Development (ms-vscode-remote.remote-*)

6. First Build

Windows (Visual Studio)

# Configure with preset
cmake --preset windows-vs2022-release

# Build
cmake --build build-msvc --config Release --parallel 8

# Run tests
cd build-msvc
ctest -C Release --output-on-failure

Linux (GCC/Ninja)

# Configure with preset
cmake --preset linux-gcc-release

# Build
cmake --build build-wsl --parallel $(nproc)

# Run tests
cd build-wsl
ctest --output-on-failure

Docker

# Build container
docker build -f docker/Dockerfile.themis-server -t themis-server .

# Run tests in container
docker run --rm themis-server ctest

🛠️ Development Workflow

Daily Workflow

Pull latest changes

git checkout develop
git pull origin develop

Create feature branch
```
git checkout -b feature/my-feature
```
Make changes - Edit code, add tests

Pre-commit validation - Runs automatically on commit

git add .
git commit -m "feat: Add my feature"
# Pre-commit hooks run here

Push and create PR

git push origin feature/my-feature
# Create PR to 'develop' branch

Code Quality

Before committing:

# Format code
clang-format -i src/**/*.cpp

# Run linter
clang-tidy src/**/*.cpp

# Run tests
cmake --build build --target test

# Check coverage (if enabled)
cmake --build build --target coverage

Pre-commit does this automatically!

Building for Different Targets

Minimal Build (Fastest)

cmake -B build-minimal \
    -DTHEMIS_ENABLE_LLM=OFF \
    -DTHEMIS_BUILD_RPC_FRAMEWORK=OFF \
    -DTHEMIS_BUILD_TESTS=OFF
cmake --build build-minimal

Full Build with LLM & GPU

cmake -B build-full \
    -DTHEMIS_ENABLE_LLM=ON \
    -DTHEMIS_ENABLE_GPU=ON \
    -DTHEMIS_BUILD_RPC_FRAMEWORK=ON
cmake --build build-full

Debug Build

cmake --preset linux-gcc-debug  # or windows-vs2022-debug
cmake --build build-debug

Runtime Environment Variables

ThemisDB reads the following environment variables at startup to tune behavior without requiring a rebuild:

Config Path Resolver (Cache)

Variable	Default	Valid Range	Description
`THEMIS_CONFIG_CACHE_CAPACITY`	`1000`	`10`–`100000`	Maximum number of resolved config paths held in the LRU cache. Increase for deployments with many unique config paths.
`THEMIS_CONFIG_CACHE_TTL_SECONDS`	`300`	`1`–`86400`	Entry time-to-live in seconds. Lower values force more frequent filesystem re-checks; higher values reduce I/O.

If an out-of-range or non-integer value is provided, ThemisDB prints a warning to stderr at startup and uses the default.

Example:

# Double cache capacity, halve TTL
export THEMIS_CONFIG_CACHE_CAPACITY=2000
export THEMIS_CONFIG_CACHE_TTL_SECONDS=150
./themisdb

Inspect the active configuration at runtime via the ConfigPathResolver::currentCacheConfig() API or the Prometheus metric themis_config_cache_ttl_seconds.

Pre-commit Hooks Failing

Issue: Hooks fail on first run

Solution:

# Run hooks on all files to fix formatting
pre-commit run --all-files

# Commit the fixes
git add .
git commit -m "chore: Apply pre-commit fixes"

vcpkg Package Not Found

Issue: CMake can't find a package

Solution:

# Verify vcpkg installation
vcpkg list

# Reinstall specific package
vcpkg install <package> --triplet x64-windows  # or x64-linux

# Clear CMake cache and reconfigure
rm -rf build-*
cmake --preset <your-preset>

IntelliSense Not Working

Issue: VS Code doesn't recognize code

Solution:

# 1. Regenerate compile_commands.json
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

# 2. Restart VS Code C++ extension
# Command Palette → "C/C++: Reset IntelliSense Database"

# 3. Verify configuration
# Check .vscode/c_cpp_properties.json has correct paths

Build Errors

Issue: CMake configuration fails

Solution:

# Check CMAKE_PREFIX_PATH
cmake -L build | grep PREFIX_PATH

# For vcpkg issues on Windows:
.\scripts\fix-cmake-prefix-path.ps1 -Action build

# For Linux:
export CMAKE_PREFIX_PATH="/opt/vcpkg/installed/x64-linux"

🐳 Dev Container Details

What's Included

Ubuntu 22.04 base
C++ build tools (GCC, Clang, Ninja)
CMake 3.26+
vcpkg pre-installed
Code quality tools (clang-format, clang-tidy, cppcheck)
Debugging tools (gdb, lldb)
Pre-commit hooks

Customization

Edit .devcontainer/devcontainer.json:

{
  "remoteEnv": {
    "THEMIS_BUILD_TYPE": "Debug",  // Change build type
    "VCPKG_ROOT": "/opt/vcpkg"
  },
  "features": {
    // Add more dev container features
  }
}

Volume Mounts

Persistent data:

themisdb-vcpkg-cache - vcpkg packages cache

Port Forwarding

8080 - ThemisDB Server
9090 - Prometheus Metrics

📚 Additional Resources

Documentation

Copilot Instructions - AI development guide
Contributing Guide - Contribution guidelines
Architecture - System design
Build Guides - Platform-specific builds

Module Guides

External Resources

🤝 Getting Help

Issues: Open an issue with label area:documentation
Discussions: Use GitHub Discussions
Questions: Ask in team chat

Last Updated: 2026-02-12
Version: 1.0

FilesExpand file tree

SETUP.md

Latest commit

History

SETUP.md

File metadata and controls

ThemisDB Development Environment Setup Guide

🎯 Quick Setup (Recommended)

Option 1: Dev Container (Fastest)

Option 2: Local Setup

📋 Detailed Setup Instructions

1. Prerequisites

All Platforms

Windows

Linux

macOS

2. Clone Repository

3. Install Pre-commit Hooks

Windows

Linux/macOS

4. Configure third-party dependencies

Windows

Linux/macOS

5. Configure VS Code (Optional but Recommended)

6. First Build

Windows (Visual Studio)

Linux (GCC/Ninja)

Docker

🛠️ Development Workflow

Daily Workflow

Code Quality

Building for Different Targets

Minimal Build (Fastest)

Full Build with LLM & GPU

Debug Build

Runtime Environment Variables

Config Path Resolver (Cache)

Pre-commit Hooks Failing

vcpkg Package Not Found

IntelliSense Not Working

Build Errors

🐳 Dev Container Details

What's Included

Customization

Volume Mounts

Port Forwarding

📚 Additional Resources

Documentation

Module Guides

External Resources

🤝 Getting Help