Skip to main content

ML Service Setup Guide

Complete setup guide for the ML Service development environment.

🚀 Prerequisites​

System Requirements​

  • Python 3.9+: Required for FastAPI and ML libraries
  • Git: Version control
  • Virtual Environment: Python venv or conda
  • Redis: Caching (optional for development)

Optional​

  • Docker: For containerized development
  • PostgreSQL: Local database (can use Supabase cloud)

📦 Installation​

1. Clone Repository​

git clone https://github.com/your-org/daggh.git
cd daggh/python-ml-service

2. Create Virtual Environment​

# Using venv
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Using conda
conda create -n mlservice python=3.9
conda activate mlservice

3. Install Dependencies​

pip install -r requirements.txt

4. Environment Configuration​

Create .env file:

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/daggh

# Supabase (if using cloud)
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key

# TMDB API
TMDB_API_KEY=your_tmdb_api_key

# Redis (optional)
REDIS_URL=redis://localhost:6379

# FastAPI
DEBUG=True
HOST=0.0.0.0
PORT=8000

🚀 Running the Service​

Development Mode​

# With auto-reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# With specific environment
uvicorn main:app --reload --env-file .env

Production Mode​

# Basic production run
uvicorn main:app --host 0.0.0.0 --port 8000

# With workers
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

🧪 Testing Setup​

Run Tests​

# All tests
pytest

# With coverage
pytest --cov=app tests/

# Specific test file
pytest tests/test_recommendations.py

Test Database​

# Create test database
createdb daggh_test

# Run migrations for test DB
alembic upgrade head

📊 Development Tools​

API Documentation​

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc
  • OpenAPI JSON: http://localhost:8000/openapi.json

Code Quality​

# Linting
flake8 app/
black app/
isort app/

# Type checking
mypy app/

🔧 Configuration​

Database Setup​

# Database connection example
from sqlalchemy import create_engine
from app.core.config import settings

engine = create_engine(settings.DATABASE_URL)

Redis Setup​

# Redis connection example
import redis
from app.core.config import settings

redis_client = redis.from_url(settings.REDIS_URL)

🐳 Docker Setup​

Development with Docker​

# Build image
docker build -t ml-service .

# Run container
docker run -p 8000:8000 ml-service

# Docker Compose
docker-compose up -d

Docker Environment​

Create docker-compose.yml:

version: "3.8"
services:
  ml-service:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/daggh
    depends_on:
      - db
      - redis

  db:
    image: postgres:13
    environment:
      POSTGRES_DB: daggh
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:alpine

volumes:
  postgres_data:

🔍 Debugging​

Common Issues​

Import Errors: Ensure virtual environment is activated

Database Connection: Verify DATABASE_URL and database server

Port Conflicts: Change port in uvicorn command

Dependencies: Run pip install -r requirements.txt

Debug Mode​

# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)

# FastAPI debug mode
app = FastAPI(debug=True)

📚 Next Steps​

Setup complete? Start exploring our architecture documentation!