Deployment

This project is containerized and deployed on Hugging Face Spaces using a custom Dockerfile. This guide explains the structure of the Dockerfile and key considerations for deploying FastAPI apps on Spaces with Docker SDK.

📦 Base Image

FROM python:3.9

We use the official Python 3.9 image for compatibility and stability across most Python libraries and tools.

👤 Create a Non-Root User

RUN useradd -m -u 1000 user
USER user
ENV PATH="/home/user/.local/bin:$PATH"

Hugging Face Spaces requires that containers run as a non-root user with UID 1000.
We also prepend the user's local binary path to PATH for Python package accessibility.

🗂️ Set Working Directory

WORKDIR /app

All application files will reside under /app for consistency and clarity.

📋 Install Dependencies

COPY --chown=user ./requirements.txt requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt

Copies the dependency list with correct file ownership.
Uses --no-cache-dir to reduce image size.
Ensures the latest compatible versions are installed.

🔡 Download Language Model (Optional)

RUN python -m spacy download en_core_web_sm || echo "Failed to download model"

Downloads the small English NLP model required by SpaCy.
Uses || echo ... to prevent build failure if the download fails (optional safeguard).

📁 Copy Project Files

COPY --chown=user . /app

Copies the entire project source into the container, setting correct ownership for Hugging Face's user-based execution.

🌐 Start the FastAPI Server

CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

Launches the FastAPI app using uvicorn.
Port 7860 is mandatory for Docker-based Hugging Face Spaces deployments.
app:app refers to the FastAPI() instance in app.py.

✅ Deployment Checklist

Ensure your main file is named app.py or adjust CMD accordingly.
All dependencies should be listed in requirements.txt.
If using models like SpaCy, verify they are downloaded or bundled.
Test your Dockerfile locally with docker build before pushing to Hugging Face.

📚 References

Hugging Face Docs: Spaces Docker SDK
Uvicorn Docs: https://www.uvicorn.org/
SpaCy Models: https://spacy.io/models

Happy deploying!
P.S. Try not to break stuff. 😅