Quickstart

Navigation: Home > Getting Started

ThemisDB — Quick Start

Version: 2.4.0-alpha
Get ThemisDB running in minutes. This is the canonical Step 1 from README.md. For full development-environment setup, continue with SETUP.md.

---

Prerequisites

Tool	Minimum version	Notes
Docker	24.x	Recommended for fastest start
CMake	3.20	Required for building from source
C++ compiler	GCC 12 / Clang 16 / MSVC 17	C++20 required
Python	3.8+	For tooling scripts
Git	2.x

---

Option 0 — Windows Package Manager (WinGet)

The fastest way to install ThemisDB on Windows:

winget install ThemisDB.ThemisDB

This installs the latest stable Community release as a portable executable.
After installation themis_server is available on the PATH.

# Start the server
themis_server --config %LOCALAPPDATA%\ThemisDB\config.yaml

# Upgrade to a newer release
winget upgrade ThemisDB.ThemisDB

Note: WinGet packaging is currently under review at microsoft/winget-pkgs #392825.
Until merged, install via Docker (Option 1) or from source (Option 3).

Option 1 — Docker (recommended)

1. Pull and run

# Latest stable Community release
docker pull themisdb/themisdb:latest

docker run -d \
  --name themisdb \
  -p 8765:8765 \
  -v themisdb_data:/data \
  themisdb/themisdb:latest

# Pin to a specific version
docker run -d \
  --name themisdb \
  -p 8765:8765 \
  -v themisdb_data:/data \
  themisdb/themisdb:2.4.0-alpha

Port	Protocol
8765	HTTP/REST API + WebSocket
8766	ThemisDB Wire Protocol V2 (mTLS)
8770	QUIC/HTTP3 transport (optional)
8771	gRPC (optional)

2. Verify the server is healthy

curl http://localhost:8765/health
# {"status":"ok","version":"2.4.0-alpha"}

3. Run your first query (AQL)

curl -X POST http://localhost:8765/v2/query \
  -H 'Content-Type: application/json' \
  -d '{"query": "SELECT 1 AS hello"}'

4. Docker Compose (with Prometheus + Grafana)

docker compose up -d

The bundled docker-compose.yml starts ThemisDB, Prometheus, and Grafana with pre-configured dashboards.

---

Option 1b — Linux Native Packages

For server deployments without Docker:

# Debian / Ubuntu
wget https://github.com/makr-code/ThemisDB/releases/download/v2.4.0-alpha/themisdb_2.4.0-alpha_amd64.deb
sudo dpkg -i themisdb_2.4.0-alpha_amd64.deb

# RHEL / Fedora
wget https://github.com/makr-code/ThemisDB/releases/download/v2.4.0-alpha/themisdb-2.4.0-alpha-1.x86_64.rpm
sudo rpm -i themisdb-2.4.0-alpha-1.x86_64.rpm

# Generic (TGZ)
wget https://github.com/makr-code/ThemisDB/releases/download/v2.4.0-alpha/themisdb-2.4.0-alpha-Linux-x86_64.tar.gz
tar xzf themisdb-2.4.0-alpha-Linux-x86_64.tar.gz
cd themisdb-2.4.0-alpha-Linux-x86_64
./bin/themis_server --config ./config/config.yaml --data-dir ./data

DEB/RPM packages are built in .github/workflows/ci-release.yml (Linux linux-release packaging lane) and attached to each GitHub Release.

Option 2 — Dev Container (VS Code)

1. Install Docker Desktop and the Dev Containers VS Code extension.
2. Clone the repository and open it in VS Code.
3. Press Ctrl+Shift+P → Dev Containers: Reopen in Container.

The container installs all toolchains and dependencies automatically.

---

Option 3 — Build from Source

1. Clone

git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB
git submodule update --init --recursive

2. Install pre-commit hooks and use CMake-native dependency bootstrap

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

# Bootstrap dependencies directly via CMake (cross-platform)
cmake --preset linux-release -DTHEMIS_AUTO_BOOTSTRAP_DEPS=ON

# Windows (PowerShell)
.\scripts\setup-pre-commit.ps1
cmake --preset windows-release -DTHEMIS_AUTO_BOOTSTRAP_DEPS=ON

This installs vcpkg dependencies, llama.cpp, whisper.cpp, and ffmpeg into the repository tree.

The repository uses a pinned vcpkg submodule for consistent Windows/Linux/Docker dependency resolution.

Build reality check: the repo is currently expected to work with a repo-local vcpkg checkout at ./vcpkg or with CMake-native bootstrap enabled via -DTHEMIS_AUTO_BOOTSTRAP_DEPS=ON. Fresh clones and some Windows developer environments may not have the toolchain file in place yet; in those cases, the canonical recovery path is to reconfigure with the bootstrap flag rather than to hard-code a machine-specific absolute path. Local overrides belong in CMakeUserPresets.json, not in checked-in build instructions.

Local developer note: vcpkg can occasionally show a dirty submodule state because of generated lock/temp files from local tool runs. That is a working-tree artifact from the toolchain, not a source-code change. If needed, ignore those generated files in the submodule's local git exclude instead of documenting them as repository policy.

3. Configure and build (Community edition)

Linux x64:

cmake --preset linux-release
cmake --build --preset linux-release

Windows x64 (aus einer VS Developer Command Prompt):

cmake --preset windows-release
cmake --build --preset windows-release

Available presets (see CMakePresets.json):

Preset	Platform	Build type
linux-release	Linux x64 (GCC)	Release
linux-debug	Linux x64 (GCC)	Debug
linux-arm64-release	Linux arm64 (GCC cross)	Release
linux-arm64-debug	Linux arm64 (GCC cross)	Debug
windows-release	Windows x64 (MSVC)	Release
windows-debug	Windows x64 (MSVC)	Debug

Local overrides (custom compiler paths, feature flags) go in CMakeUserPresets.json — copy from CMakeUserPresets.json.example. That file is gitignored.

4. Run the server

./build/linux-release/themis_server --data-dir ./data

5. Run the tests

ctest --preset linux-release --output-on-failure

---

First Steps

Create a collection and insert a document

curl -X POST http://localhost:8765/v2/collections \
  -H 'Content-Type: application/json' \
  -d '{"name": "products", "schema": {}}'

curl -X POST http://localhost:8765/v2/collections/products/documents \
  -H 'Content-Type: application/json' \
  -d '{"name": "Widget A", "price": 9.99, "tags": ["sale"]}'

Query with AQL

curl -X POST http://localhost:8765/v2/query \
  -H 'Content-Type: application/json' \
  -d '{"query": "FOR doc IN products FILTER doc.price < 10 RETURN doc"}'

Vector search

curl -X POST http://localhost:8765/v2/search/vector \
  -H 'Content-Type: application/json' \
  -d '{"collection": "products", "vector": [0.1, 0.2, 0.3], "top_k": 5}'

---

Next Steps

Topic	Resource
Full API reference	[[docs/api/API_REFERENCE.md
AQL language guide	aql/
Architecture	ARCHITECTURE.md
Configuration	config/
Security hardening	SECURITY.md
Production deployment	docs/de/guides/guides_deployment.md
Performance tuning	docs/performance/PERFORMANCE_EXPECTATIONS.md
Examples	examples/
Full documentation	docs/Home.md

---

Troubleshooting

Container exits immediately (Exit 139 / SIGSEGV)
Set enable_response_cache = false, or move to the current tagged image line documented in CHANGELOG.md / VERSION (2.4.0-alpha at this sync point).

Port already in use
Change the host port mapping: -p 18765:8765.

Build fails: missing vcpkg package
Reconfigure with -DTHEMIS_AUTO_BOOTSTRAP_DEPS=ON; CMake then initializes missing submodules and bootstraps vcpkg automatically.

More help: SUPPORT.md · GitHub Discussions · FAQ

---

Zuletzt geprueft (Root-Sync): 2026-08-28

---

ThemisDB 1.9.0-beta · Home · Module-Index · GitHub · Issues