Deploying the Backend to Hugging Face Spaces

Hugging Face Spaces is a free Docker-based hosting platform. It gives you 2 vCPU, 16GB RAM, and 50GB storage — plenty for this project.

What You'll Learn

• Creating a Hugging Face Space
• Deploying a Dockerized Flask app to production
• Managing secrets (API keys) on Hugging Face
• Connecting your mobile app to the production backend

Prerequisites

• A Hugging Face account — sign up at https://huggingface.co/join
• Git installed and configured (git --version)
• Your project committed to a git repo on GitHub (or any git remote)
• A Supabase PostgreSQL database ready (see database-production.md)
• Your OPENAI_API_KEY ready

Step 1: Ensure Your Dockerfile.prod Is Ready

The production Dockerfile should already exist at backend/Dockerfile.prod from the Docker setup section. If not, create it:

FROM python:3.13-slim

WORKDIR /app

COPY app/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt gunicorn

COPY app/ ./app/
COPY wsgi.py .

EXPOSE 8000

CMD ["gunicorn", "wsgi:app", "--bind", "0.0.0.0:8000"]

The wsgi.py entry point should also exist at backend/wsgi.py:

from app import create_app

app = create_app()

Step 2: Create a README.md for Your Space

Hugging Face Spaces requires a README.md at the root of the Space repo. Create backend/README.md:

---
title: AI Project Backend
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
---

# AI Project Backend

Flask chat backend for the Agentic Chat project.

The metadata block (---) tells Hugging Face this is a Docker Space.

Step 3: Create the Hugging Face Space

1. Go to https://huggingface.co/new-space
2. Set Space Name to aiproject-backend
3. Under Space SDK, select Docker
4. Choose Dockerfile (not a template)
5. Set Visibility to Public (you can change to Private later)
6. Click Create Space

Hugging Face gives you a git repo URL like:

https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend

Step 4: Push Your Backend Code to the Space

Since the backend code is in a subdirectory (backend/), use git subtree to push only that folder:

cd aiproject

# Add the Hugging Face Space as a remote
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend

# Push the backend folder as the root of the Space repo
git subtree push --prefix backend space main

Enter your Hugging Face username and password (or a write token from https://huggingface.co/settings/tokens) when prompted.

First-time only: Git will ask for credentials. Use a Hugging Face write token (create one at Settings → Access Tokens) instead of your password.

Alternative: Manual Upload

If git subtree is confusing, you can: 1. Clone your Space repo: git clone https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend 2. Copy the backend files into it: cp -r aiproject/backend/* aiproject-backend/ 3. Commit and push

Step 5: Set Environment Secrets

Hugging Face needs your API keys and database URL. They should never be in your code.

1. Go to your Space: https://huggingface.co/spaces/YOUR_USERNAME/aiproject-backend
2. Click the Settings tab
3. Scroll to Repository Secrets (NOT Variables — Secrets are encrypted)
4. Add these secrets:

Important: Secrets are not available during the build phase — only at runtime. This is fine for our setup since Gunicorn reads them at startup.

Step 6: Watch the Build

1. Go to the Builder tab of your Space
2. You'll see the Docker build logs
3. The first build takes 2-5 minutes (downloading python:3.13-slim and installing dependencies)
4. When complete, the status shows "Running"

Step 7: Get Your Production URL

After deployment, your Space is available at:

https://YOUR_USERNAME-aiproject-backend.hf.space

Test it:

curl https://YOUR_USERNAME-aiproject-backend.hf.space/api/status
# → {"status":"ok"}

If you see {"status":"ok"}, your backend is live!

Step 8: Update Your Mobile App

In mobile/App.tsx, update the API URL to point to your production backend:

const API_BASE_URL = "https://YOUR_USERNAME-aiproject-backend.hf.space";

Rebuild or re-deploy your mobile app with EAS Build (see mobile-production.md).

Troubleshooting

Pre-Deploy Checklist

Before you push to Hugging Face Spaces, run this checklist:

# 1. Lint your code
ruff check backend/

# 2. Run all tests
cd backend && python -m pytest tests/ -v

# 3. Build the production Docker image locally
docker build -f Dockerfile.prod -t aiproject-prod .

# 4. Check for any .env references that should be secrets
grep -r "os.getenv" app/

If all four steps pass, you're ready to deploy. The CI/CD pipeline (see deployment/ci-cd.md) automates steps 1 and 2 on every push.

Next Steps

• Add a database — See database-production.md to connect Supabase PostgreSQL
• Set up a custom domain — Hugging Face Spaces supports custom domains (Settings → Custom Domain)
• Upgrade your Space — For more resources, see Hugging Face's pricing (but the free tier is generous enough for this project)