README_HF.md

Hugging Face Spaces Deployment Guide

Overview

This backend is configured for deployment on Hugging Face Spaces using Docker.

Requirements

Environment Variables

Set these in Hugging Face Spaces Settings → Repository secrets:

Required:

• DATABASE_URL - PostgreSQL connection string
• JWT_SECRET - Secret key for JWT tokens
• PAYSTACK_SECRET_KEY - Paystack secret key
• PAYSTACK_PUBLIC_KEY - Paystack public key

Optional:

• PORT - Server port (default: 7860 for HF Spaces)
• NODE_ENV - Environment (default: production)
• PINATA_JWT - Pinata IPFS JWT token
• GATEWAY_URL - IPFS gateway URL
• NGN_PER_USD - Exchange rate fallback (default: 750)
• POINT_VALUE_USD - Point value in USD (default: 0.05)
• CURRENCY_API_KEY - For dynamic exchange rates
• FIXER_API_KEY - Alternative exchange rate API

Hugging Face Spaces Configuration

1. Hardware Requirements

• CPU: 2 vCPU minimum
• RAM: 4GB minimum
• Disk: 10GB minimum

2. Dockerfile Setup

The repository includes a Dockerfile that:

• Uses Node.js 20 Alpine (lightweight)
• Multi-stage build for optimization
• Runs as non-root user for security
• Exposes port 7860 (HF Spaces default)

3. Space Settings

In your Hugging Face Space:

1. Go to Settings
2. Set Docker as the SDK
3. Set hardware requirements
4. Add environment variables (secrets)

4. Port Configuration

Hugging Face Spaces automatically maps port 7860. The Dockerfile and server are configured to use this port.

Build Process

Local Build Test

# Build the Docker image
docker build -t zurri-backend .

# Run locally
docker run -p 7860:7860 --env-file .env zurri-backend

Production Build

The Dockerfile uses multi-stage build:

1. Builder stage: Installs all dependencies and builds TypeScript
2. Production stage: Only copies production dependencies and built files

Database Setup

PostgreSQL on Hugging Face Spaces

Hugging Face Spaces doesn't provide managed databases. Options:

1. External Database (Recommended)

   • Use services like Render, Supabase, or Railway
   • Set DATABASE_URL in HF Spaces secrets

2. Database in Docker (Not recommended for production)

   • Could run PostgreSQL in same container (not ideal)

Health Check

The Dockerfile includes a health check endpoint:

GET /health

Hugging Face Spaces will automatically monitor this.

Logs

View logs in Hugging Face Spaces:

• Go to your Space
• Click Logs tab
• Monitor server output and errors

API Documentation

Once deployed, access Swagger UI at:

https://your-space.hf.space/docs

Troubleshooting

Port Issues

• Ensure PORT=7860 is set (or use SPACE_PORT)
• Check Hugging Face Spaces logs for port binding errors

Database Connection

• Verify DATABASE_URL is correctly set
• Check database allows connections from HF Spaces IPs
• Test connection locally before deploying

Build Failures

• Check Dockerfile syntax
• Verify all dependencies in package.json
• Review build logs in HF Spaces

Memory Issues

• Increase RAM allocation in Space settings
• Check for memory leaks in application
• Monitor memory usage in logs

Security Considerations

1. Environment Variables: Never commit secrets to git
2. CORS: Configure CORS for your frontend domain
3. Rate Limiting: Already configured in app.ts
4. Helmet: Security headers enabled
5. Non-root User: Dockerfile runs as non-root user

Monitoring

Health Endpoint

curl https://your-space.hf.space/health

API Endpoints

All endpoints are documented in Swagger:

https://your-space.hf.space/docs

Deployment Checklist

• Set all required environment variables in HF Spaces
• Configure external PostgreSQL database
• Set correct CORS origins (if needed)
• Test health endpoint after deployment
• Verify database connection
• Test payment integration (Paystack)
• Monitor logs for errors
• Update frontend API URLs to point to HF Space

Notes

• Hugging Face Spaces provides HTTPS automatically
• Webhook URLs need to be updated to HF Space URL
• Paystack webhook URL: https://your-space.hf.space/api/wallet/webhook/paystack
• Callback URL: https://your-space.hf.space/api/wallet/callback

Support

For issues:

1. Check Hugging Face Spaces logs
2. Review application logs
3. Verify environment variables
4. Test endpoints via Swagger UI