wehub-resource-sync
216 lines
4.1 KiB
Markdown
216 lines
4.1 KiB
Markdown
# 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)
|