docker-build.md

Docker Build & Run Instructions

🐳 Docker Setup for RecSys-HP

This guide explains how to build and run the RecSys-HP recommendation system in a Docker container.

Prerequisites

• Docker installed on your system
• All model artifacts in src/artifacts/ directory
• Dataset files in datasets/ directory

Build Docker Image

# Navigate to project root
cd /path/to/RecSys-HP

# Build the Docker image (this will take 5-10 minutes)
docker build -t recsys-hp:latest .

# Or build with a specific tag
docker build -t recsys-hp:v1.0 .

Run Docker Container

Basic Run (Recommended)

# Run the container
docker run -d \
  --name recsys-hp-app \
  -p 8000:8000 \
  recsys-hp:latest

# View logs
docker logs recsys-hp-app

# Follow logs in real-time
docker logs -f recsys-hp-app

Run with Volume Mounts (Development)

# Mount datasets and artifacts for easy updates
docker run -d \
  --name recsys-hp-dev \
  -p 8000:8000 \
  -v $(pwd)/datasets:/app/datasets \
  -v $(pwd)/src/artifacts:/app/src/artifacts \
  recsys-hp:latest

Access the Application

Once the container is running:

• Web App: http://localhost:8000/
• API Docs: http://localhost:8000/docs
• API Info: http://localhost:8000/api
• Health Check: http://localhost:8000/health

Useful Docker Commands

# Check container status
docker ps

# Stop the container
docker stop recsys-hp-app

# Start the container
docker start recsys-hp-app

# Remove the container
docker rm recsys-hp-app

# View container resource usage
docker stats recsys-hp-app

# Execute commands in running container
docker exec -it recsys-hp-app bash

# View container logs
docker logs recsys-hp-app

Troubleshooting

Container won't start?

# Check logs for errors
docker logs recsys-hp-app

# Common issues:
# 1. Missing artifacts in src/artifacts/
# 2. Missing datasets in datasets/
# 3. Port 8000 already in use

Check if artifacts are present:

docker exec recsys-hp-app ls -la /app/src/artifacts/
docker exec recsys-hp-app ls -la /app/datasets/

Use different port:

# Run on port 8080 instead
docker run -d --name recsys-hp-app -p 8080:8000 recsys-hp:latest
# Access at http://localhost:8080/

Image Information

• Base Image: python:3.10-slim
• Node.js Version: 18-alpine (build stage only)
• Final Image Size: ~1.5-2GB (includes all ML dependencies)
• Exposed Port: 8000
• Health Check: Enabled (checks /health endpoint)

Production Deployment

For production deployment, consider:

# Run with restart policy
docker run -d \
  --name recsys-hp-prod \
  --restart unless-stopped \
  -p 8000:8000 \
  recsys-hp:latest

# Or use docker-compose (recommended for production)

Environment Variables

The container supports these environment variables:

docker run -d \
  --name recsys-hp-app \
  -p 8000:8000 \
  -e PYTHONUNBUFFERED=1 \
  -e LOG_LEVEL=info \
  recsys-hp:latest

The Docker container includes both the React frontend and FastAPI backend in a single image, making deployment simple and efficient! 🚀