# Docker Setup for Memvid Core
This document describes how to use Docker with the Memvid Core Rust library.
## Quick Start
### Development Environment
```bash
# From project root or docker/core directory
cd docker/core
docker-compose up -d dev
# Enter the container
docker-compose exec dev bash
# Inside container, you can run:
cargo build
cargo test
cargo run --example basic_usage
```
### Run Tests
```bash
# Run all tests
cd docker/core
docker-compose run --rm test
# Or build test image manually (from project root)
docker build -f docker/core/Dockerfile.test -t memvid-test .
docker run --rm memvid-test
```
### Build Release
```bash
# Build release version
cd docker/core
docker-compose run --rm build
# Or build manually (from project root)
docker build -f docker/core/Dockerfile -t memvid-core:latest .
```
## Docker Images
### 1. Development Image (`Dockerfile.dev`)
Full development environment with all tools:
```bash
# From project root
docker build -f docker/core/Dockerfile.dev -t memvid-dev .
docker run -it --rm -v $(pwd):/app memvid-dev bash
```
**Features:**
- Rust toolchain 1.92
- All build dependencies
- Cargo watch (optional)
- Volume mounting for live development
### 2. Test Image (`Dockerfile.test`)
Optimized for running tests:
```bash
# From project root
docker build -f docker/core/Dockerfile.test -t memvid-test .
docker run --rm memvid-test
```
**Features:**
- Rust toolchain 1.92
- Test dependencies
- Runs tests automatically
### 3. Production Build (`Dockerfile`)
Multi-stage build for optimized production image:
```bash
# From project root
docker build -f docker/core/Dockerfile -t memvid-core:latest .
```
**Features:**
- Multi-stage build (smaller final image)
- Only runtime dependencies
- Optimized release build
## Docker Compose
### Services
- **`dev`** - Development environment with live code mounting
- **`test`** - Test runner
- **`build`** - Release builder
### Usage
```bash
# Start development environment
docker-compose up -d dev
# Run tests
docker-compose run --rm test
# Build release
docker-compose run --rm build
# Stop all services
docker-compose down
```
## Examples
### Run Examples in Docker
```bash
# Development container
docker-compose exec dev cargo run --example basic_usage
# With features
docker-compose exec dev cargo run --example pdf_ingestion --features lex,pdf_extract
```
### Memory-Constrained Testing
Test OOM prevention with memory limits:
```bash
# Test with memory limit (for OOM testing)
docker run --rm --memory=150m --memory-swap=150m \
-v $(pwd):/app \
memvid-test cargo test --features encryption --test encryption_capsule
```
### Build with Specific Features
```bash
# Build with all features
docker-compose exec dev cargo build --release --all-features
# Build with specific features
docker-compose exec dev cargo build --release --features lex,vec,encryption
```
## Volume Mounts
The docker-compose setup uses volumes for:
- **Source code** - Live mounting for development
- **Cargo cache** - Speeds up builds
- **Target cache** - Preserves build artifacts
## CI/CD Integration
### GitHub Actions Example
```yaml
name: Docker Build
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build Docker image
run: docker build -t memvid-core:test .
- name: Run tests
run: docker run --rm memvid-core:test cargo test
```
## Troubleshooting
### Build Fails
```bash
# Clean build
docker-compose down -v
docker-compose build --no-cache
```
### Permission Issues
```bash
# Fix permissions
sudo chown -R $USER:$USER .
```
### Out of Memory
```bash
# Increase Docker memory limit in Docker Desktop settings
# Or use memory limits in docker run:
docker run --memory=2g --memory-swap=2g ...
```
## Best Practices
1. **Use docker-compose** for development
2. **Cache volumes** for faster builds
3. **Multi-stage builds** for production
4. **Test in containers** to match CI/CD environment
5. **Use .dockerignore** to exclude unnecessary files
## Related
- [CLI Docker Setup](../cli/README.md)
- [Docker Overview](../README.md)
- [Main Project README](../../README.md)
- [Contributing Guide](../../CONTRIBUTING.md)