Hugging Face's logo

Spaces:
Seth0330
/
EZOFIS-IRP
Sleeping

App Files Community
EZOFIS-IRP / HUGGINGFACE_SPACES_SETUP.md
Seth
Update
8e8c6a4
preview code
|
raw
history blame contribute delete
7.43 kB

Hugging Face Spaces Setup Guide

This guide provides specific instructions for deploying the EZOFIS OCR application to Hugging Face Spaces.

Prerequisites

  1. ✅ Firebase project configured
  2. ✅ Brevo account set up
  3. ✅ Hugging Face account with a Space created

Step 1: Frontend Environment Variables

Set these in Hugging Face Spaces → Settings → Variables and secrets:

Variables (Public):

  • VITE_FIREBASE_API_KEY → Set as Secret (Private) ✅
  • VITE_FIREBASE_AUTH_DOMAIN → Set as Variable (Public)
  • VITE_FIREBASE_PROJECT_ID → Set as Variable (Public)
  • VITE_FIREBASE_STORAGE_BUCKET → Set as Variable (Public)
  • VITE_FIREBASE_MESSAGING_SENDER_ID → Set as Variable (Public)
  • VITE_FIREBASE_APP_ID → Set as Variable (Public)
  • VITE_API_BASE_URL → Set as Variable (Public) (e.g., https://your-username-ezofisocr.hf.space)

Note: These variables are used during the Docker build process. The Dockerfile has been updated to accept them as build arguments.

Step 2: Backend Environment Variables

Set these in Hugging Face Spaces → Settings → Variables and secrets:

Secrets (Private):

  1. FIREBASE_SERVICE_ACCOUNT_JSON

    • Get your Firebase service account JSON file (from Firebase Console → Project Settings → Service accounts)
    • Copy the entire JSON content (all in one line or formatted)
    • Paste it as the value for this secret
    • Example format:
      {"type":"service_account","project_id":"your-project","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","client_email":"...","client_id":"...","auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"..."}

  2. BREVO_API_KEY

    • Get from Brevo → Settings → API Keys
    • Format: xkeysib-...

  3. JWT_SECRET_KEY

    • Generate a secure random key:
      openssl rand -hex 32
    • Or use Python:
      python -c "import secrets; print(secrets.token_hex(32))"

Variables (Public):

  1. BREVO_SENDER_EMAIL

    • Your verified sender email in Brevo
    • Example: noreply@yourdomain.com

  2. BREVO_SENDER_NAME

    • Display name for emails
    • Example: EZOFIS AI

  3. FRONTEND_URL

    • Your Hugging Face Space URL
    • Format: https://your-username-ezofisocr.hf.space
    • Replace your-username with your actual Hugging Face username

Step 3: Verify Dockerfile

The Dockerfile has been updated to accept frontend environment variables as build arguments. Make sure your Dockerfile includes:

# Accept build arguments for Vite environment variables
ARG VITE_FIREBASE_API_KEY
ARG VITE_FIREBASE_AUTH_DOMAIN
ARG VITE_FIREBASE_PROJECT_ID
ARG VITE_FIREBASE_STORAGE_BUCKET
ARG VITE_FIREBASE_MESSAGING_SENDER_ID
ARG VITE_FIREBASE_APP_ID
ARG VITE_API_BASE_URL

# Set as environment variables so Vite can access them during build
ENV VITE_FIREBASE_API_KEY=$VITE_FIREBASE_API_KEY
ENV VITE_FIREBASE_AUTH_DOMAIN=$VITE_FIREBASE_AUTH_DOMAIN
ENV VITE_FIREBASE_PROJECT_ID=$VITE_FIREBASE_PROJECT_ID
ENV VITE_FIREBASE_STORAGE_BUCKET=$VITE_FIREBASE_STORAGE_BUCKET
ENV VITE_FIREBASE_MESSAGING_SENDER_ID=$VITE_FIREBASE_MESSAGING_SENDER_ID
ENV VITE_FIREBASE_APP_ID=$VITE_FIREBASE_APP_ID
ENV VITE_API_BASE_URL=$VITE_API_BASE_URL

Step 4: Deploy

  1. Commit and push your code to the Hugging Face Space repository
    • Make sure frontend/build-env.sh is included in your commit
  2. Wait for the build to complete (check the "Logs" tab)
    • Look for "Checking environment variables..." messages in the build logs
    • Verify all variables show "✓ ... is set" (not "WARNING: ... is not set")
  3. Test the deployment:
    • Open your Space URL
    • Try Firebase login
    • Try OTP authentication

Important: After setting or updating environment variables in Hugging Face Spaces, you need to rebuild the Space for the changes to take effect. The frontend is built during the Docker build process, so environment variable changes require a rebuild.

Troubleshooting

Build Fails with "VITE_* variables not found"

  • Solution: Make sure all VITE_* variables are set in Spaces → Variables and secrets
  • Hugging Face Spaces automatically makes environment variables available during build
  • The Dockerfile uses a build script to create a .env file from these variables

Firebase Authentication Not Working - "auth/invalid-api-key" Error

  • Check: VITE_FIREBASE_API_KEY is set correctly (as a Secret) and contains the full API key
  • Check: All other VITE_FIREBASE_* variables are set with correct values
  • Check: After updating variables, rebuild the Space (the frontend needs to be rebuilt)
  • Check: Firebase Console → Authentication → Sign-in method → Google is enabled
  • Check: The API key matches the one in Firebase Console → Project Settings → Your apps
  • Solution: If the error persists, check the build logs to see if the .env file is being created correctly

OTP Emails Not Sending

  • Check: BREVO_API_KEY is set correctly (as a Secret)
  • Check: BREVO_SENDER_EMAIL is verified in Brevo
  • Check: BREVO_SENDER_NAME is set
  • Check: You haven't exceeded Brevo free tier (300 emails/day)

Backend Errors

  • Check: FIREBASE_SERVICE_ACCOUNT_JSON contains the full JSON (all fields)
  • Check: JWT_SECRET_KEY is set
  • Check: FRONTEND_URL matches your Space URL exactly

Environment Variables Checklist

Frontend (Build-time):

  • VITE_FIREBASE_API_KEY (Secret)
  • VITE_FIREBASE_AUTH_DOMAIN (Variable)
  • VITE_FIREBASE_PROJECT_ID (Variable)
  • VITE_FIREBASE_STORAGE_BUCKET (Variable)
  • VITE_FIREBASE_MESSAGING_SENDER_ID (Variable)
  • VITE_FIREBASE_APP_ID (Variable)
  • VITE_API_BASE_URL (Variable)

Backend (Runtime):

  • FIREBASE_SERVICE_ACCOUNT_JSON (Secret)
  • BREVO_API_KEY (Secret)
  • JWT_SECRET_KEY (Secret)
  • BREVO_SENDER_EMAIL (Variable)
  • BREVO_SENDER_NAME (Variable)
  • FRONTEND_URL (Variable)

Notes

  1. Build vs Runtime: Frontend variables (VITE_*) are used during Docker build, backend variables are used at runtime.

  2. Secrets vs Variables:

    • Use Secrets for sensitive data (API keys, private keys, JWT secrets)
    • Use Variables for non-sensitive configuration (URLs, display names)

  3. Firebase Service Account JSON: When copying the JSON, make sure to include the entire content, including the private_key field with newlines preserved (they should be \n in the JSON string).

  4. Space URL: Your Space URL format is https://{username}-{space-name}.hf.space. Make sure FRONTEND_URL and VITE_API_BASE_URL match this exactly.

Support

If you encounter issues:

  1. Check the build logs in Hugging Face Spaces
  2. Verify all environment variables are set correctly
  3. Ensure Firebase and Brevo are properly configured
  4. Review the main setup guide: FIREBASE_OTP_SETUP.md