docs/deployment.md

#  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

```dockerfile
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

```dockerfile
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

```dockerfile
WORKDIR /app
```

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

---

## 📋 Install Dependencies

```dockerfile
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)

```dockerfile
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

```dockerfile
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

```dockerfile
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

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

---

## 📚 References

* Hugging Face Docs: [Spaces Docker SDK](https://huggingface.co/docs/hub/spaces-sdks-docker)
* Uvicorn Docs: [https://www.uvicorn.org/](https://www.uvicorn.org/)
* SpaCy Models: [https://spacy.io/models](https://spacy.io/models)

---

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


[🔙 Back to Main README](../README.md)