DEPLOYMENT.md

Deploying to Hugging Face Spaces

This guide will help you deploy your FastAPI application to Hugging Face Spaces.

Prerequisites

1. A Hugging Face account (sign up at https://huggingface.co/)
2. Git installed on your system
3. Your Jira API credentials

Deployment Steps

Step 1: Create a New Space

1. Go to https://huggingface.co/new-space
2. Fill in the details:
   • Space name: Choose a name (e.g., enterprise-intelligence-api)
   • License: MIT (or your preferred license)
   • Select SDK: Choose Docker
   • Space hardware: Select the free tier or upgrade if needed
3. Click "Create Space"

Step 2: Push Your Code to Hugging Face

1. Initialize Git (if not already done):

   git init
   git add .
   git commit -m "Initial commit for HF deployment"
   

2. Add Hugging Face Space as remote:

   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   

   Replace YOUR_USERNAME and YOUR_SPACE_NAME with your actual values.

3. Push to Hugging Face:

   git push hf main
   

   If you're on a different branch, use:

   git push hf master:main
   

Step 3: Configure Environment Variables (Secrets)

Your API needs environment variables (like Jira credentials). To add them:

1. Go to your Space settings: https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME/settings

2. Scroll down to Repository secrets

3. Add the following secrets one by one:

   • JIRA_URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
   • JIRA_EMAIL: Your Jira email
   • JIRA_API_TOKEN: Your Jira API token
   • DEBUG: Set to false
   • ENVIRONMENT: Set to production
   • Any other secrets from your .env.example file

4. Click "Add secret" for each one

Step 4: Wait for Build

1. Hugging Face will automatically build your Docker container
2. Check the Logs tab to monitor the build process
3. Once complete, your API will be available at:

   https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
   

Step 5: Test Your Deployment

1. Visit your Space URL
2. Add /docs to access the FastAPI Swagger documentation:

   https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs
   

3. Test the endpoints to ensure everything works

Important Notes

Free Tier Limitations

• The free tier may have limited resources
• The app might go to sleep after inactivity
• Consider upgrading to a paid tier for production workloads

Environment Variables via Dockerfile (Alternative)

If you don't want to use secrets (not recommended for sensitive data), you can set default values in the Dockerfile:

ENV JIRA_URL=https://example.atlassian.net
ENV DEBUG=false

Updating Your Deployment

To update your deployed app:

git add .
git commit -m "Update: description of changes"
git push hf main

Hugging Face will automatically rebuild and redeploy.

Troubleshooting

Build Fails

• Check the Logs tab in your Space
• Ensure all dependencies in requirements.txt are compatible
• Make sure the Dockerfile syntax is correct

App Crashes on Startup

• Check if all required environment variables are set in Secrets
• Review the application logs in the Space's Logs tab
• Ensure the port is 7860 (required by HF Spaces)

Can't Access the API

• Verify the Space is "Running" (not "Sleeping" or "Building")
• Check the URL is correct: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
• Free tier spaces may take a moment to wake up

Quick Reference Commands

# Clone your existing Space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# Add changes
git add .
git commit -m "Your message"
git push

# Force push (use carefully)
git push --force

Resources

• Hugging Face Spaces Documentation
• Docker Spaces Guide
• FastAPI Documentation

Support

If you encounter issues:

1. Check Hugging Face Spaces documentation
2. Review the build logs in your Space
3. Visit Hugging Face forums or Discord for community support