README-HF.md

# 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:

```bash
# 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

1. Go to https://huggingface.co/new-space
2. Choose a name for your space
3. Set the **SDK** to `Docker`
4. Set visibility (Public/Private)
5. 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
1. Go to your newly created Space
2. Click "Files" tab
3. Upload all required files
4. Rename `Dockerfile.hf` to `Dockerfile`

#### Option B: Git (Recommended)
```bash
# 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
1. Check that all required files are uploaded
2. Verify `package.json` has all dependencies
3. Check Dockerfile syntax

### Runtime Issues
1. Check Space logs in the Hugging Face interface
2. Ensure port 7860 is properly configured
3. 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

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