Hugging Face's logo

Spaces:
nice-bill
/
deepshelf-api
Sleeping

App Files Community
deepshelf-api / DEPLOYMENT_NOTES.md
nice-bill's picture
nice-bill
initial commit
cdb73a8
preview code
|
raw
history blame contribute delete
2.76 kB

Deployment Notes & Configuration Guide

Created on: November 30, 2025 Project Status: MVP Complete / Production Ready

This document serves as a "black box" recovery manual. If you return to this project in the future and need to redeploy it, follow these exact steps.

1. Environment Variables

These are the variables you MUST set in your cloud provider (Render/Vercel/Railway) for the app to function.

Backend (FastAPI / Docker)

Deployment Platform: Render (Web Service) or Railway

Variable Name Value (Example/Format) Purpose
HF_DATASET_ID nice-bill/book-recommender-data CRITICAL. Tells the app where to download the embeddings/parquet files from Hugging Face.
GROQ_API_KEY gsk_... Required for the "Why this match?" AI explanations. Get a key at console.groq.com.
HF_TOKEN hf_... (Optional) Only required if you made your Hugging Face dataset PRIVATE.
PORT 8000 (Render sets this automatically, but good to know).

Frontend (React / Vite)

Deployment Platform: Vercel or Netlify

Variable Name Value (Example/Format) Purpose
VITE_API_URL https://your-app-name.onrender.com Points the frontend to your live backend. Do not add a trailing slash.

2. Build Settings

Backend

  • Runtime: Docker
  • Dockerfile Path: docker/Dockerfile.backend
  • Context Directory: . (Root of the repo)
  • Start Command: (Handled automatically by Dockerfile: scripts/download_data.py && uvicorn ...)

Frontend

  • Framework Preset: Vite
  • Root Directory: frontend
  • Build Command: npm run build
  • Output Directory: dist
  • Node Version: 18.x or 20.x

3. "Cold Start" Recovery

If the application is crashing on startup after a long time:

  1. Check Hugging Face Data:

    • Go to: https://huggingface.co/datasets/nice-bill/book-recommender-data
    • Ensure these 4 files still exist: books_cleaned.parquet, book_embeddings.npy, cluster_cache.pkl, embedding_metadata.json.

  2. Check Groq API:

    • API keys sometimes expire or quotas change. Generate a new one if the "Why this match?" feature fails.

  3. Local Run:

    • Backend: uv run src/book_recommender/api/main.py
    • Frontend: cd frontend && npm run dev

4. Key Features Summary

  • Search: Semantic search using all-MiniLM-L6-v2 embeddings.
  • Explanation: Uses Llama 3 (via Groq) to explain recommendations.
  • Data Layer: Self-healing. Downloads data on boot if missing.
  • UI: React + Tailwind + Lucide Icons. Features "Glassmorphism" and tactile hover effects.