Add Dockerfile and deployment guide for Hugging Face Spaces

Dockerfile

@@ -0,0 +1,37 @@
+# Use Python 3.10 slim as base for a smaller image
+FROM python:3.10-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies for OpenCV, MediaPipe, and C++ compilation
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application
+COPY . .
+
+# Compile the C++ engagement module
+RUN python setup.py build_ext --inplace
+
+# Expose the port used by Hugging Face Spaces
+EXPOSE 7860
+
+# Run the application with uvicorn
+# We use 0.0.0.0 to allow external access and 7860 as the port
+CMD ["python", "src/main.py"]

deployment_guide.md

@@ -0,0 +1,41 @@
+# Deploying to Hugging Face Spaces (Option A)
+
+Hugging Face Spaces is the best free option for FocusFlow because it supports Docker, allowing us to compile the C++ module in the cloud.
+
+## Step 1: Create the Space
+1. Go to [Hugging Face Spaces](https://huggingface.co/spaces).
+2. Click **"Create new Space"**.
+3. Name your space (e.g., `FocusFlow`).
+4. Select **Docker** as the SDK.
+5. Choose **"Blank"** template.
+6. Set visibility to **Public** or **Private**.
+7. Click **Create Space**.
+
+## Step 2: Push your code
+Since your code is already on GitHub, you can either:
+
+### Method A: Connect GitHub (Easiest)
+1. On your new Space page, go to **Settings**.
+2. Find the **"Connected GitHub Repository"** section.
+3. Link your `kush-rc/FocusFlow` repository.
+4. Hugging Face will automatically build and deploy whenever you push to GitHub.
+
+### Method B: Manually Push via Git
+1. Get the Git URL of your Space (ends in `.git`).
+2. Add it as a new remote:
+   ```bash
+   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/FocusFlow
+   ```
+3. Push to Hugging Face:
+   ```bash
+   git push -f hf main
+   ```
+
+## Step 3: Monitoring the Build
+- Once pushed, go to the **"Logs"** tab in your Space.
+- You will see the Docker image building and the C++ module compiling.
+- Once finished, the Status will change to **"Running"**.
+
+## Important Notes
+- **Port**: Hugging Face requires the app to listen on port `7860`. The `Dockerfile` and `main.py` are already configured for this.
+- **Webcam**: Ensure your site is accessed via `https` (Hugging Face provides this automatically) so the browser allows camera access.

src/main.py

@@ -363,5 +363,12 @@ async def websocket_stream(websocket: WebSocket):
             db.end_session(session_id)
 
 if __name__ == "__main__":
+    import os
+    # Hugging Face Spaces and other cloud providers often use the PORT env var
+    port = int(os.environ.get("PORT", 8000))
+    # In a container/cloud, we must use 0.0.0.0
+    host = "0.0.0.0"
+    
+    print(f"🚀 FocusFlow starting on http://{host}:{port}")
     # Disable reload because writing to the database triggers a server restart loop
-    uvicorn.run("src.main:app", host="0.0.0.0", port=8000, reload=False)
+    uvicorn.run("src.main:app", host=host, port=port, reload=False)