docs/DEPLOYMENT.md

Deployment Guide: Hugging Face Spaces

This guide deploys the FastAPI app as a Hugging Face Docker Space.

Hugging Face Spaces supports Docker apps, and a Docker Space is configured by adding sdk: docker to the YAML block at the top of the Space README.md. Docker Spaces commonly expose port 7860; the app, Dockerfile, and Space metadata must all use the same port.

Official references:

• Hugging Face Docker Spaces: https://huggingface.co/docs/hub/main/spaces-sdks-docker
• Hugging Face Spaces overview: https://huggingface.co/docs/hub/main/spaces-overview

What Gets Deployed

The Hugging Face Space should deploy the backend API and built-in analyzer UI:

• GET / serves app/static/index.html
• GET /health returns API health
• POST /analyze rates a GitHub username

The separate React documentation website in website/ can be deployed separately as a static site. The Space deployment described here focuses on the FastAPI app.

Prerequisites

1. A Hugging Face account.
2. Git installed locally.
3. Optional but recommended: a valid GitHub token for higher API limits.

Create a GitHub token and save it as a Hugging Face Space secret named:

GITHUB_TOKEN

Public/no-token mode works, but GitHub rate limits unauthenticated requests heavily.

Create The Space

1. Go to https://huggingface.co/spaces
2. Click Create new Space.
3. Choose an owner and Space name.
4. Select Docker as the SDK.
5. Choose public or private visibility.
6. Create the Space.

Space README Metadata

In the Hugging Face Space repository, the top of README.md should include:

---
title: GitHub Profile AI Reviewer
emoji: 🧪
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
---

The important lines are:

sdk: docker
app_port: 7860

Hugging Face Dockerfile

Hugging Face expects the app to listen on the configured Space port. Use this Dockerfile for the Space:

FROM python:3.12-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV APP_HOST=0.0.0.0
ENV APP_PORT=7860

COPY requirements.txt ./
RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 7860

CMD uvicorn app.main:app --host "${APP_HOST}" --port "${APP_PORT}"

Why this differs from local Docker:

• Hugging Face Docker Spaces commonly expose 7860.
• The production API does not require torch or transformers; default requirements.txt is enough.
• requirements-ml.txt is optional and should not be installed unless you intentionally want the heavier ML stack.

Environment Variables And Secrets

Set these in the Hugging Face Space Settings tab.

Secrets:

GITHUB_TOKEN=your_valid_github_token_here

Variables:

GITHUB_API_URL=https://api.github.com/graphql
GITHUB_REST_API_URL=https://api.github.com
GITHUB_PUBLIC_REPO_LIMIT=20
GITHUB_FETCH_COMMIT_COUNTS=false
GITHUB_CACHE_TTL_SECONDS=900
APP_HOST=0.0.0.0
APP_PORT=7860
SCORING_BACKEND=heuristic

Do not commit .env to Hugging Face or GitHub. Use Hugging Face Space secrets for private values.

Push Code To The Space

From your local repo:

git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
git push hf main

If your app is on another branch, push that branch to main on the Space:

git push hf your-branch:main

Hugging Face rebuilds the Space automatically after each push.

Test The Deployed App

After the Space finishes building:

https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/

Health check:

https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health

Analyze request:

curl -X POST https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/analyze \
  -H "Content-Type: application/json" \
  -d '{"username":"octocat"}'

Expected response includes:

{
  "username": "octocat",
  "rating_score": 72,
  "public_activity": {
    "public_commits": 18,
    "public_prs_created": 4
  },
  "model_info": {
    "data_source": "graphql"
  }
}

Troubleshooting

Space stuck on Starting

Check that all three ports match:

• Space README: app_port: 7860
• Dockerfile: EXPOSE 7860
• Uvicorn command: --port 7860

GitHub API rate limit exceeded

Add a valid GITHUB_TOKEN as a Hugging Face Space secret and restart/rebuild the Space.

Bad credentials

Your GITHUB_TOKEN is invalid or expired. Replace it in Space secrets, then restart the Space.

Module import errors

Make sure requirements.txt is installed in the Dockerfile. Do not rely on local virtual environments.

Heavy image or slow build

Use the lightweight requirements.txt. Avoid installing requirements-ml.txt unless you actually need torch, transformers, and langgraph.

React Documentation Website

The React documentation website lives in website/.

To deploy it separately:

cd website
npm install
npm run build

Deploy website/dist/ to a static host such as Hugging Face Static HTML Space, Netlify, Vercel, or GitHub Pages.

If deploying the React docs to a Hugging Face Static HTML Space, configure the Space as Static HTML and upload the built dist/ contents.