DOCKER_README.md
This guide covers running LocalGPT using Docker containers with local Ollama for optimal performance.
# 1. Install Ollama locally
curl -fsSL https://ollama.ai/install.sh | sh
# 2. Start Ollama server
ollama serve
# 3. Install required models (in another terminal)
ollama pull qwen3:0.6b
ollama pull qwen3:8b
# 4. Clone and start LocalGPT
git clone https://github.com/your-org/rag-system.git
cd rag-system
./start-docker.sh
# 5. Access the application
open http://localhost:3000
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
ā Frontend āāāāāā Backend āāāāāā RAG API ā
ā (Container) ā ā (Container) ā ā (Container) ā
ā Port: 3000 ā ā Port: 8000 ā ā Port: 8001 ā
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
ā
ā API calls
ā¼
āāāāāāāāāāāāāāāāāāā
ā Ollama ā
ā (Local/Host) ā
ā Port: 11434 ā
āāāāāāāāāāāāāāāāāāā
Why Local Ollama?
./lancedb/ ā Vector database storage./index_store/ ā Document indexes and metadata./shared_uploads/ ā Uploaded document files./backend/chat_data.db ā SQLite chat history databaseAll containers share access to document storage and databases through bind mounts.
# Ollama Configuration
OLLAMA_HOST=http://host.docker.internal:11434
# Service Configuration
NODE_ENV=production
RAG_API_URL=http://rag-api:8001
NEXT_PUBLIC_API_URL=http://localhost:8000
# Database Paths (inside containers)
DATABASE_PATH=/app/backend/chat_data.db
LANCEDB_PATH=/app/lancedb
UPLOADS_PATH=/app/shared_uploads
The system uses these models by default:
Qwen/Qwen3-Embedding-0.6B (1024 dimensions)qwen3:0.6b (fast) or qwen3:8b (high quality)# Start all services
./start-docker.sh
# Stop all services
./start-docker.sh stop
# Restart services
./start-docker.sh stop && ./start-docker.sh
# Check container status
./start-docker.sh status
docker compose ps
# View live logs
./start-docker.sh logs
docker compose logs -f
# View specific service logs
docker compose logs -f rag-api
docker compose logs -f backend
docker compose logs -f frontend
# Start manually
docker compose --env-file docker.env up --build -d
# Stop manually
docker compose down
# Rebuild specific service
docker compose build --no-cache rag-api
docker compose up -d rag-api
# Test all endpoints
curl -f http://localhost:3000 && echo "ā
Frontend OK"
curl -f http://localhost:8000/health && echo "ā
Backend OK"
curl -f http://localhost:8001/models && echo "ā
RAG API OK"
curl -f http://localhost:11434/api/tags && echo "ā
Ollama OK"
# RAG API container (most debugging happens here)
docker compose exec rag-api bash
# Backend container
docker compose exec backend bash
# Frontend container
docker compose exec frontend sh
# Test RAG system initialization
docker compose exec rag-api python -c "
from rag_system.main import get_agent
agent = get_agent('default')
print('ā
RAG System OK')
"
# Test Ollama connection from container
docker compose exec rag-api curl http://host.docker.internal:11434/api/tags
# Check environment variables
docker compose exec rag-api env | grep OLLAMA
# View Python packages
docker compose exec rag-api pip list | grep -E "(torch|transformers|lancedb)"
# Monitor container resources
docker stats
# Check disk usage
docker system df
df -h ./lancedb ./shared_uploads
# Check memory usage by service
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"
# Check logs for specific error
docker compose logs [service-name]
# Rebuild from scratch
./start-docker.sh stop
docker system prune -f
./start-docker.sh
# Check for port conflicts
lsof -i :3000 -i :8000 -i :8001
# Verify Ollama is running
curl http://localhost:11434/api/tags
# Restart Ollama
pkill ollama
ollama serve
# Test from container
docker compose exec rag-api curl http://host.docker.internal:11434/api/tags
# Check memory usage
docker stats --no-stream
free -h # On host
# Increase Docker memory limit
# Docker Desktop ā Settings ā Resources ā Memory ā 8GB+
# Use smaller models
ollama pull qwen3:0.6b # Instead of qwen3:8b
# Clean build
docker compose build --no-cache frontend
docker compose up -d frontend
# Check frontend logs
docker compose logs frontend
# Check file permissions
ls -la backend/chat_data.db
ls -la lancedb/
# Reset permissions
chmod 664 backend/chat_data.db
chmod -R 755 lancedb/ shared_uploads/
# Test database access
docker compose exec backend sqlite3 /app/backend/chat_data.db ".tables"
qwen3:0.6b instead of qwen3:8bdocker statsdocker system prune# Nuclear option - reset everything
./start-docker.sh stop
docker system prune -a --volumes
rm -rf lancedb/* shared_uploads/* backend/chat_data.db
./start-docker.sh
Your Docker deployment is successful when:
./start-docker.sh status shows all containers healthyGood Performance:
Optimal Performance:
DOCKER_TROUBLESHOOTING.mdDocumentation/docker_usage.mdDocumentation/architecture_overview.mdREADME.md for non-Docker setupHappy Dockerizing! š³ Need help? Check the troubleshooting guide or open an issue.