docker

ThemisDB LoRA Framework - Docker Compose Setup

Complete Docker Compose environment for developing and testing the ThemisDB LoRA framework.

🚀 Quick Start (< 5 minutes)

Prerequisites

Docker ≥ 20.10
Docker Compose ≥ 2.0
Hardware: 4GB RAM minimum, 8GB recommended

Start the Environment

# Clone the repository (if not already done)
git clone https://github.com/makr-code/ThemisDB.git
cd ThemisDB/docker

# Start all services
./scripts/start.sh

That's it! The environment is now running.

📍 Access URLs

Once started, access these services:

Service	URL	Credentials
ThemisDB API	http://localhost:8529	None (dev mode)
Prometheus	http://localhost:9091	None
Grafana	http://localhost:3000	admin / admin

🏗️ Architecture

The Docker Compose setup includes:

Services

themisdb - Main ThemisDB instance with LoRA framework
- Ports: 8529 (HTTP), 8765 (AQL), 9090 (metrics)
- Built from Dockerfile.themisdb
- Persistent volumes for data and logs
prometheus - Metrics collection and monitoring
- Port: 9091 (offset to avoid conflict)
- Scrapes metrics from ThemisDB every 15s
- 30-day retention by default
grafana - Metrics visualization
- Port: 3000
- Pre-configured with Prometheus datasource
- Pre-loaded LoRA framework dashboard
test-db - Isolated test database instance
- Port: 8530
- Used for integration tests
- Separate data volume
vcpkg-builder - Dependency cache service
- Caches vcpkg packages across builds
- Speeds up rebuild times

Network

All services run on a private bridge network (themis-network) with subnet 172.28.0.0/16.

Volumes

Persistent data stored in Docker volumes:

themisdb-data - Database files
themisdb-logs - Application logs
prometheus-data - Metrics history
grafana-data - Dashboards and settings
vcpkg-cache - Build dependencies cache

🎯 Usage Modes

Production Mode (Default)

Start with optimized builds and production settings:

./scripts/start.sh prod

Development Mode

Start with debug builds, hot-reload, and development tools:

./scripts/start.sh dev

Features:

Source code mounted for live editing
Debug symbols enabled
AddressSanitizer for memory debugging
Additional debugging ports exposed
Development tools container included

Access development container:

docker-compose exec dev-tools bash

Test Mode

Run automated tests in isolated environment:

./scripts/start.sh test

Features:

Runs all LoRA framework tests
Uses ephemeral storage (tmpfs)
Exits automatically after tests
Resource limits for CI environments

📝 Configuration Files

ThemisDB Configuration

Edit config/themisdb.yaml to customize:

Server ports and networking
Storage and database settings
LoRA framework parameters
Logging levels
Performance tuning

Example:

llm:
  lora:
    enabled: true
    adapters:
      max_loaded: 5
      cache_size_mb: 1024

Prometheus Configuration

Edit prometheus/prometheus.yml to:

Add scrape targets
Configure retention policies
Set up alerting rules

Grafana Dashboards

Add custom dashboards to grafana/dashboards/. They will be auto-loaded on startup.

🛠️ Common Operations

View Logs

# All services
./scripts/logs.sh

# Specific service
./scripts/logs.sh themisdb

# Follow logs
./scripts/logs.sh -f

Stop Services

# Stop services (preserve data)
./scripts/stop.sh

# Stop and remove all data
./scripts/stop.sh --clean

Reset Environment

# WARNING: Deletes all data!
./scripts/reset.sh

Run Tests

./scripts/test.sh

Rebuild Services

# Rebuild specific service
docker-compose build themisdb

# Rebuild all services
docker-compose build

# Rebuild and restart
docker-compose up -d --build

Execute Commands in Container

# ThemisDB shell
docker-compose exec themisdb bash

# Run tests manually
docker-compose exec themisdb /usr/local/bin/test_lora_framework

# Run benchmarks
docker-compose exec themisdb /usr/local/bin/bench_lora_framework

📊 Monitoring

Grafana Dashboards

Access Grafana at http://localhost:3000 (admin/admin).

Pre-loaded dashboards:

LoRA Framework Overview - Key metrics and performance
- Adapter load times
- Memory usage
- Cache hit rates
- Inference latency

Prometheus Metrics

Access Prometheus at http://localhost:9091.

Key LoRA metrics:

lora_adapter_load_time_seconds - Time to load adapters
lora_adapter_memory_usage_bytes - Memory per adapter
lora_inference_latency_milliseconds - Inference time
lora_cache_hit_rate - Cache efficiency
lora_adapters_loaded_count - Number of loaded adapters
lora_training_progress - Training job progress

🔧 Troubleshooting

Services Won't Start

Check ports are available:

# Check if ports are in use
lsof -i :8529
lsof -i :9091
lsof -i :3000

# Stop conflicting services or change ports in docker-compose.yml

Check Docker resources:

# Ensure Docker has enough resources (Settings > Resources)
# Minimum: 4GB RAM, 2 CPUs

Build Failures

Clear Docker cache:

docker-compose build --no-cache
docker system prune -a

Check vcpkg cache:

# Remove vcpkg cache if corrupted
docker volume rm themisdb-lora_vcpkg-cache
docker volume rm themisdb-lora_vcpkg-downloads

Services Crash or Restart

Check logs:

./scripts/logs.sh themisdb

Check resource usage:

docker stats

Increase memory limits: Edit docker-compose.yml and increase memory limits.

Grafana Dashboard Not Loading

Re-provision dashboards:

docker-compose restart grafana

# Or manually import from grafana/dashboards/

Database Connection Errors

Verify service is healthy:

docker-compose ps
curl http://localhost:8529/health

Wait for startup: ThemisDB needs 30-40 seconds to fully initialize.

Test Failures

Run tests with verbose output:

docker-compose exec themisdb /usr/local/bin/test_lora_framework --gtest_verbose=true

Check test database:

curl http://localhost:8530/health

⚡ Performance Optimization

Build Performance

Use cached builds:

# vcpkg cache is preserved across builds
docker-compose build  # Fast after first build

Parallel builds:

# Already configured in Dockerfile with -j$(nproc)

Layer caching:

# Dockerfile uses multi-stage builds for optimal caching

Runtime Performance

Allocate more resources: Edit .env or docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: '4'
      memory: 8G

Use SSD for volumes: Docker volumes should be on SSD for best performance.

Tune ThemisDB settings: Edit config/themisdb.yaml:

performance:
  thread_pool_size: 8
  query_cache_size_mb: 512

🚢 Production Deployment

Important Notes

⚠️ This setup is designed for development and testing, not production!

For production deployment:

Use proper secrets management (not hardcoded passwords)
Enable authentication and TLS
Configure proper resource limits
Set up monitoring and alerting
Use orchestration (Kubernetes, Docker Swarm)
Configure backups and disaster recovery

Production Checklist

🔗 Related Documentation

LoRA Build Guide - Building without Docker
LoRA Testing Guide - Detailed testing
LoRA Usage Examples - API usage
Docker Build Strategy - Build details

🤝 Contributing

When making changes:

Test with all three modes (prod, dev, test)
Update this README if adding new features
Validate configurations before committing
Keep Docker images lean and efficient

📄 License

This Docker setup is part of ThemisDB and follows the same license (MIT).

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: ThemisDB Docs

Happy Developing! 🚀

Name		Name	Last commit message	Last commit date
parent directory ..
community		community
config		config
enterprise		enterprise
grafana		grafana
hyperscaler		hyperscaler
nginx		nginx
prometheus		prometheus
scripts		scripts
.env.example		.env.example
DOCKER_BUILD_STRATEGY_QUICKREF.md		DOCKER_BUILD_STRATEGY_QUICKREF.md
Dockerfile.ethics-ai		Dockerfile.ethics-ai
Dockerfile.themisdb		Dockerfile.themisdb
Dockerfile.unified		Dockerfile.unified
README.md		README.md
VCPKG_ARIA2_STRATEGY.md		VCPKG_ARIA2_STRATEGY.md
docker-compose.chimera-integration.yml		docker-compose.chimera-integration.yml
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.ethics.yml		docker-compose.ethics.yml
docker-compose.gpu-examples.yml		docker-compose.gpu-examples.yml
docker-compose.prebuild.yml		docker-compose.prebuild.yml
docker-compose.test.yml		docker-compose.test.yml
docker-compose.yml		docker-compose.yml
vcpkg-community.json		vcpkg-community.json
vcpkg-enterprise.json		vcpkg-enterprise.json
vcpkg-hyperscaler.json		vcpkg-hyperscaler.json
vcpkg-minimal.json		vcpkg-minimal.json

FilesExpand file tree

docker

Directory actions

More options

Directory actions

More options

Latest commit

History

docker

Folders and files

parent directory

README.md

ThemisDB LoRA Framework - Docker Compose Setup

🚀 Quick Start (< 5 minutes)

Prerequisites

Start the Environment

📍 Access URLs

🏗️ Architecture

Services

Network

Volumes

🎯 Usage Modes

Production Mode (Default)

Development Mode

Test Mode

📝 Configuration Files

ThemisDB Configuration

Prometheus Configuration

Grafana Dashboards

🛠️ Common Operations

View Logs

Stop Services

Reset Environment

Run Tests

Rebuild Services

Execute Commands in Container

📊 Monitoring

Grafana Dashboards

Prometheus Metrics

🔧 Troubleshooting

Services Won't Start

Build Failures

Services Crash or Restart

Grafana Dashboard Not Loading

Database Connection Errors

Test Failures

⚡ Performance Optimization

Build Performance

Runtime Performance

🚢 Production Deployment

Important Notes

Production Checklist

🔗 Related Documentation

🤝 Contributing

📄 License

💬 Support