memvid--memvid/docker/core/README.md

Docker Setup for Memvid Core

This document describes how to use Docker with the Memvid Core Rust library.

Quick Start

Development Environment

# 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

# 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

# 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:

# 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:

# 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:

# 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

# 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

# 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:

# 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

# 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

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

# Clean build
docker-compose down -v
docker-compose build --no-cache

Permission Issues

# Fix permissions
sudo chown -R $USER:$USER .

Out of Memory

# 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
• Docker Overview
• Main Project README
• Contributing Guide