deployment_guide.md

Deploying Chatsmith to Hugging Face Spaces

This guide explains how to deploy your Chatsmith application (React Frontend + FastAPI Backend) to Hugging Face Spaces for free.

Prerequisites

• A Hugging Face account.

Steps

1. Create a New Space

1. Go to Hugging Face Spaces and click Create new Space.
2. Space Name: Enter a name (e.g., chatsmith-app).
3. License: Choose one (e.g., MIT).
4. SDK: Select Docker.
5. Template: Select Blank.
6. Visibility: Public or Private.
7. Click Create Space.

2. Configure Secrets (Environment Variables)

Your app needs OpenAI and Supabase keys.

1. In your Space, go to Settings.
2. Scroll to the Variables and secrets section.
3. Click New secret and add the following (copy from your local .env file):
   • OPENAI_API_KEY
   • SUPABASE_URL
   • SUPABASE_ANON_KEY
   • ENABLE_METRICS_LOGGING (Set to true to enable Supabase logging)

3. Upload Code

You can upload files via the web interface or use Git. Since you have the code locally:

Option A: Drag and Drop (Easiest for one-off)

1. Go to the Files tab of your Space.
2. Click Add file -> Upload files.
3. Open your local chatsmith-main folder.
4. Select all files inside (backend, frontend, Dockerfile, etc.).
5. Drag and drop them into the web interface.
   • Important: Do NOT drag the chatsmith-main folder itself. Drag the contents.
   • Tip: You can skip the node_modules folder if it exists, as it will be recreated by Docker.
6. Commit the changes.

Option B: Git (Recommended)

1. In your local terminal, initialize git if not already:

   git init
   git add .
   git commit -m "Initial commit"
   

2. Add the Hugging Face remote (find the command in your Space's "Clone repository" button):

   git remote add space https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME
   

3. Push to the Space:

   git push --force space master:main
   

   Note: If asked for a password, you must use a Hugging Face Access Token with write permissions (Settings -> Access Tokens), NOT your account password.

   Authentication Helper (if needed):

   git config --global credential.helper store
   

4. Wait for Build

• Once files are uploaded, Hugging Face will automatically detect the Dockerfile and start building.
• Click the App tab to see the build logs.
• It may take a few minutes to build the frontend and install Python dependencies.
• Once "Running", your app will be live!

Troubleshooting

• Build Failed: Check the logs in the App tab.
• Runtime Error: Ensure your Secrets are set correctly in the Settings tab.