HF-DATASET-SETUP.md

🤗 Hugging Face Dataset Setup Guide

Overview

This server now uses Hugging Face Dataset for persistent storage of device tokens instead of local files. This ensures that device data is preserved across Space restarts and provides better data management.

🚀 Quick Setup

1. Generate Hugging Face Token

1. Go to Hugging Face Settings
2. Click "Create new token"
3. Name: houzou-notification-server
4. Type: Write (required for dataset operations)
5. Copy the token

2. Configure Space Secrets

1. Go to your Space Settings → Secrets and variables
2. Add these secrets:

HF_TOKEN = hf_your_token_here
HF_DATASET_ID = Detomo/houzou-devices  (optional, defaults to this)

3. Required Secrets Summary

Your Space needs these secrets:

FIREBASE_SERVICE_ACCOUNT = {your firebase config JSON}
HF_TOKEN = hf_your_write_token_here
HF_DATASET_ID = Detomo/houzou-devices (optional)

📊 Dataset Structure

The dataset will be automatically created with:

datasets/Detomo/houzou-devices/
├── README.md           # Dataset documentation
└── devices.json        # Device tokens and metadata

devices.json Format:

[
  [
    "device-id-1",
    {
      "token": "fcm_token_here",
      "lastUpdated": "2024-01-01T00:00:00.000Z",
      "platform": "iOS",
      "appVersion": "1.0.0",
      "registered": true
    }
  ]
]

🔧 Features

✅ Automatic Dataset Management

• Creates dataset if it doesn't exist
• Handles permissions automatically
• Provides fallback to in-memory storage

✅ Persistent Storage

• Device tokens survive Space restarts
• Automatic backup to HF dataset
• Version control for device data

✅ Error Handling

• Graceful fallback if HF API is unavailable
• Detailed logging for troubleshooting
• Continues operation even if dataset access fails

🔍 Verification

Check Dataset Status

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

Response includes:

{
  "message": "Houzou Medical Notification Server",
  "status": "running",
  "hfDataset": {
    "enabled": true,
    "datasetId": "Detomo/houzou-devices",
    "hasToken": true
  },
  "deviceCount": 5
}

View Dataset

1. Go to: https://huggingface.co/datasets/Detomo/houzou-devices
2. Check devices.json for your device data

🐛 Troubleshooting

Dataset Not Created

• Verify HF_TOKEN has Write permissions
• Check Space logs for error messages
• Ensure token is valid and not expired

Data Not Saving

• Check if HF API is responding
• Verify dataset permissions
• Server will continue with in-memory storage as fallback

Common Errors

403 Forbidden

• Token doesn't have write permissions
• Token is expired or invalid

404 Not Found

• Dataset doesn't exist (will be auto-created)
• Wrong dataset ID

Rate Limiting

• HF API has rate limits
• Server will retry automatically

🔄 Migration from File Storage

If you're migrating from file-based storage:

1. Backup existing data: Download your current devices.json
2. Set up HF dataset: Follow steps above
3. Deploy updated server: The server will automatically use HF dataset
4. Verify: Check that devices are loaded correctly

📋 Environment Variables

# Required
HF_TOKEN=hf_your_write_token_here
FIREBASE_SERVICE_ACCOUNT={"type":"service_account",...}

# Optional
HF_DATASET_ID=Detomo/houzou-devices
PORT=7860
NODE_ENV=production

🎯 Benefits

• ✅ Persistent: Data survives Space restarts
• ✅ Reliable: Automatic fallback mechanisms
• ✅ Scalable: No file permission issues
• ✅ Traceable: Version history in dataset
• ✅ Secure: Tokens stored in HF infrastructure

🔗 Links

• Hugging Face Hub API
• Dataset Management
• Access Tokens

---

Ready to deploy! Your notification server will now use HF Dataset for persistent storage. 🚀