Hugging Face Spaces Deployment Guide

This guide explains how to deploy your Invoice Generator application to Hugging Face Spaces.

Prerequisites

Hugging Face account
Git installed locally
Application built and tested locally

Quick Start

1. Test Locally with HF Configuration

First, test your application with the Hugging Face Spaces configuration:

# Make the deployment script executable
chmod +x deploy-hf.sh

# Deploy locally using HF configuration
./deploy-hf.sh

Your app will be available at http://localhost:7860

2. Create a New Space on Hugging Face

Go to https://huggingface.co/new-space
Choose a name for your space
Set the SDK to Docker
Set visibility (Public/Private)
Click "Create Space"

3. Prepare Files for Upload

You need to upload these files to your Hugging Face Space:

Required Files:

Dockerfile (rename Dockerfile.hf to Dockerfile)
nginx.hf.conf
package.json
package-lock.json
index.html
script.js
style.css
.dockerignore

Optional Files:

README.md (Space description)
Any other assets your app needs

4. Upload to Hugging Face Spaces

Option A: Web Interface

Go to your newly created Space
Click "Files" tab
Upload all required files
Rename Dockerfile.hf to Dockerfile

Option B: Git (Recommended)

# Clone your space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy required files
cp ../path/to/your/project/Dockerfile.hf ./Dockerfile
cp ../path/to/your/project/nginx.hf.conf ./
cp ../path/to/your/project/package*.json ./
cp ../path/to/your/project/index.html ./
cp ../path/to/your/project/script.js ./
cp ../path/to/your/project/style.css ./
cp ../path/to/your/project/.dockerignore ./

# Commit and push
git add .
git commit -m "Initial deployment of Invoice Generator"
git push

5. Configure Space Settings

In your Space settings, ensure:

SDK: Docker
Port: 7860 (automatically detected)
Hardware: CPU Basic (or upgrade if needed)

File Structure for Hugging Face Spaces

your-space/
├── Dockerfile              # Renamed from Dockerfile.hf
├── nginx.hf.conf           # Nginx config for port 7860
├── package.json            # Node.js dependencies
├── package-lock.json       # Locked versions
├── index.html              # Main HTML file
├── script.js               # JavaScript code
├── style.css               # Styles
├── .dockerignore           # Docker ignore rules
└── README.md               # Space description (optional)

Key Differences from Standard Deployment

Port Configuration

Standard: Port 80/8080
Hugging Face Spaces: Port 7860 (required)

Dockerfile Changes

Uses Dockerfile.hf which configures nginx for port 7860
Includes wget for health checks
Exposes port 7860

Nginx Configuration

nginx.hf.conf listens on port 7860
Includes health check endpoint at /health
Optimized for Hugging Face Spaces environment

Troubleshooting

Build Failures

Check that all required files are uploaded
Verify package.json has all dependencies
Check Dockerfile syntax

Runtime Issues

Check Space logs in the Hugging Face interface
Ensure port 7860 is properly configured
Verify nginx configuration

Common Issues

Issue: Space shows "Building" for too long Solution: Check for missing dependencies in package.json

Issue: Application not accessible Solution: Verify nginx is listening on port 7860, not 80

Issue: Static files not loading Solution: Check file paths and nginx static file configuration

Health Check

Your deployed Space will have a health check endpoint at:

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

Production Considerations

Performance

Consider upgrading to CPU/GPU hardware if needed
Monitor Space usage and logs
Optimize bundle size for faster builds

Security

Review Content Security Policy headers
Ensure no sensitive data in client-side code
Use HTTPS (automatically provided by HF Spaces)

Monitoring

Check Space analytics in Hugging Face dashboard
Monitor build times and resource usage
Set up alerts for Space downtime

Support

Hugging Face Spaces Documentation: https://huggingface.co/docs/hub/spaces
Community Forum: https://discuss.huggingface.co/
Discord: https://discord.gg/hugging-face

Next Steps

Test your Space thoroughly after deployment
Update README.md with Space-specific information
Share your Space with the community
Consider adding a demo or usage instructions