docker_readme.md

Docker Setup for Crowd Detection API

This guide will help you dockerize and run the Crowd Detection API using Docker and Docker Compose.

📁 File Structure

Make sure your project directory has the following structure:

crowd-detection-api/
├── main.py                 # Your main FastAPI application
├── start_backend.py        # Startup script
├── requirements.txt        # Python dependencies
├── Dockerfile             # Docker image definition
├── docker-compose.yml     # Docker Compose configuration
├── .dockerignore          # Files to exclude from Docker build
├── build-and-run.sh       # Build and run script
└── uploads/               # Directory for uploaded files (created automatically)
└── models/                # Directory for AI models (created automatically)
└── logs/                  # Directory for logs (created automatically)

🚀 Quick Start

Option 1: Using the Build Script (Recommended)

1. Make the script executable:

   chmod +x build-and-run.sh
   

2. Run the interactive script:

   ./build-and-run.sh
   

3. Or run directly with commands:

   ./build-and-run.sh run      # Build and run with docker-compose
   ./build-and-run.sh simple   # Build and run simple container
   ./build-and-run.sh test     # Test API endpoints
   ./build-and-run.sh logs     # Show container logs
   ./build-and-run.sh stop     # Stop services
   

Option 2: Manual Docker Commands

1. Build the Docker image:

   docker build -t crowd-detection-api:latest .
   

2. Run the container:

   docker run -d \
     --name crowd-detection-backend \
     -p 8000:8000 \
     -v $(pwd)/uploads:/app/uploads \
     -v $(pwd)/models:/app/models \
     -v $(pwd)/logs:/app/logs \
     --restart unless-stopped \
     crowd-detection-api:latest
   

Option 3: Using Docker Compose

1. Start the services:

   docker-compose up -d
   

2. Stop the services:

   docker-compose down
   

🔍 Accessing the API

Once the container is running, you can access:

• API Base URL: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• Interactive API: http://localhost:8000/redoc

📊 Testing the API

Health Check

curl http://localhost:8000/health

Get Zones with Heatmap

curl http://localhost:8000/zones/heatmap

WebSocket Connection (Alerts)

const ws = new WebSocket('ws://localhost:8000/ws/alerts');
ws.onmessage = (event) => {
    console.log('Alert:', JSON.parse(event.data));
};

🛠️ Development Mode

For development with auto-reload:

docker run -it --rm \
  -p 8000:8000 \
  -v $(pwd):/app \
  -w /app \
  python:3.9-slim \
  bash -c "pip install -r requirements.txt && python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload"

📋 Container Management

View running containers:

docker ps

View container logs:

docker logs crowd-detection-backend -f

Execute commands in container:

docker exec -it crowd-detection-backend bash

Stop and remove container:

docker stop crowd-detection-backend
docker rm crowd-detection-backend

🔧 Configuration

Environment Variables

You can configure the container using environment variables:

docker run -d \
  --name crowd-detection-backend \
  -p 8000:8000 \
  -e PYTHONUNBUFFERED=1 \
  -e ENVIRONMENT=production \
  crowd-detection-api:latest

Volume Mounts

The container uses the following volumes:

• ./uploads:/app/uploads - For uploaded video/image files
• ./models:/app/models - For AI model cache
• ./logs:/app/logs - For application logs

🚨 Troubleshooting

Container won't start:

1. Check if port 8000 is available:

   netstat -tulpn | grep 8000
   

2. Check container logs:

   docker logs crowd-detection-backend
   

API not responding:

1. Check if container is healthy:

   docker ps
   

2. Test from inside container:

   docker exec -it crowd-detection-backend curl http://localhost:8000/health
   

Model download issues:

The container automatically downloads YOLOv8 models on first run. If this fails:

1. Check internet connectivity in container
2. Pre-download models manually:

   docker exec -it crowd-detection-backend python -c "from ultralytics import YOLO; YOLO('yolov8s.pt')"
   

🔒 Security Considerations

• The container runs as a non-root user (appuser)
• Only necessary system packages are installed
• Resource limits are configured in docker-compose.yml
• Health checks are enabled for monitoring

📈 Performance Tuning

Resource Limits

Adjust in docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: '4.0'      # Increase for better performance
      memory: 8G       # Increase for large models
    reservations:
      cpus: '2.0'
      memory: 4G

GPU Support

For GPU acceleration, add to docker-compose.yml:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: 1
          capabilities: [gpu]

🔄 Updates and Maintenance

Update the application:

1. Stop the container:

   ./build-and-run.sh stop
   

2. Rebuild and restart:

   ./build-and-run.sh run
   

Clean up Docker resources:

# Remove unused images
docker image prune

# Remove unused volumes
docker volume prune

# Remove unused networks
docker network prune

📞 Support

If you encounter issues:

1. Check the container logs
2. Verify all required files are present
3. Ensure Docker has sufficient resources allocated
4. Check network connectivity for model downloads

The API will automatically start when the container starts and includes health checks for monitoring.