Hugging Face's logo

Spaces:
StrategyStack
/
README
Sleeping

App Files Community
README / DEPLOYMENT_GUIDE.md
stackConsult's picture
stackConsult
Create DEPLOYMENT_GUIDE.md
62ca4d3 verified
preview code
|
Raw History Blame Contribute Delete
9.19 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

StrategyStack Deployment Guide

Customer-Ready Multi-Tenant Platform

This guide explains how to deploy and configure the StrategyStack Recovery, Enrichment & Outreach Platform for production use with Hugging Face Spaces.

✅ What's Already Implemented

The platform now includes:

1. OAuth Authentication

  • 🔒 Sign in with Hugging Face button
  • Automatic user authentication via gr.OAuthProfile
  • All dashboard panels protected behind authentication
  • Unauthenticated users see clear login prompts

2. Per-User Data Isolation

  • Each user's data stored in /data/users/{username}/
  • Zero data sharing between users
  • Customer data ownership model (you don't hold their data)
  • Automatic user directory creation on first access

3. Multi-Tenant Architecture

  • Session-based data loading
  • Username displayed in all panels
  • Sample data for seamless new user onboarding
  • Refresh buttons for manual data reloading

4. Data Types Supported

  • Consent events (consent_events.json)
  • Cadence branches (branches.json)
  • Diagnostic logs (diagnostics.json)
  • Extensible to any JSON-serializable data

🚀 Deployment Steps

Step 1: Enable Persistent Storage

CRITICAL: Hugging Face Spaces must have persistent storage enabled for user data to persist between sessions.

  1. Go to your Space: https://huggingface.co/spaces/StrategyStack/README
  2. Click on Settings tab
  3. Scroll to Storage section
  4. Enable Persistent storage
  5. Select storage size (recommended: 20GB minimum for multi-tenant use)
  6. Save changes

Note: Persistent storage is mounted at /data and persists across Space restarts.

Step 2: Configure Space Secrets (Optional)

If your application needs API keys for external services:

  1. Go to Settings tab

  2. Scroll to Variables and secrets section

  3. Add secrets:

    • LINKEDIN_API_KEY (if using LinkedIn integration)
    • TWILIO_API_KEY (if using Twilio integration)
    • SALESFORCE_API_KEY (if using Salesforce integration)
    • Any other API keys your agents require

  4. Access in code:

import os
linkedin_key = os.getenv('LINKEDIN_API_KEY')

Step 3: Verify OAuth Configuration

The OAuth setup is already complete:

  • ✅ README.md has hf_oauth: true in metadata (line 9)
  • ✅ app.py has gr.LoginButton() component
  • ✅ All functions accept gr.OAuthProfile parameter

No additional OAuth configuration needed!

Step 4: Test Multi-User Access

  1. Open the Space: https://huggingface.co/spaces/StrategyStack/README

  2. Click Sign in with Hugging Face

  3. Verify you see:

    • Your username displayed in panels
    • Sample data (since you're a new user)
    • All four dashboard tabs accessible

  4. Test with a second account:

    • Sign out
    • Sign in with different HF account
    • Verify data is separate from first account

📊 Monitoring & Operations

Viewing Logs

  1. Go to Space page
  2. Click on Logs dropdown (top right)
  3. Select:
    • Build - See build logs
    • Container - See runtime application logs

Space Status

  • 🟢 Running - Space is live and accepting users
  • 🔵 Building - Space is being rebuilt after code changes
  • 🔴 Runtime Error - Check container logs for errors

Restarting the Space

If you need to restart:

  1. Go to Settings tab
  2. Scroll to Sleep time settings
  3. Click Restart Space

Note: Persistent storage data survives restarts!

💾 Data Management

User Data Structure 

/data/
└── users/
    ├── username1/
    │   ├── consent_events.json
    │   ├── branches.json
    │   └── diagnostics.json
    ├── username2/
    │   ├── consent_events.json
    │   ├── branches.json
    │   └── diagnostics.json
    └── ...

Accessing User Data

The app provides helper functions:

# Load user data
user_events = load_user_data(username, "consent_events")

# Save user data
save_user_data(username, "consent_events", data)

# Get user directory
user_dir = get_user_dir(username)

Backup Strategy

Important: While persistent storage is durable, implement regular backups:

  1. Option A - Manual Backup:

    • Use Hugging Face Hub's file browser
    • Download /data directory contents
    • Store securely off-platform

  2. Option B - Automated Backup (Future Enhancement):

    • Add scheduled backup function
    • Export to external cloud storage
    • Implement via Space cron or external scheduler

⚙️ Configuration Options

Customizing Data Storage Location

Edit app.py line 9:

DATA_DIR = Path("/data")  # Change if needed

Adding New Data Types

  1. Define new data structure (JSON-serializable)
  2. Use existing functions:
# Save new data type
save_user_data(username, "campaigns", campaign_data)

# Load new data type
campaigns = load_user_data(username, "campaigns")
  1. Create UI panel to display/edit

Customizing Authentication Messages

Edit the authentication check in panel functions (app.py):

if profile is None:
    return "Your custom auth message here"

🛡️ Security Considerations

Data Isolation

  • ✅ Users cannot access other users' data
  • ✅ File paths use username for isolation
  • ✅ No centralized data storage (privacy by design)

Authentication

  • ✅ OAuth via Hugging Face (no password management needed)
  • ✅ Profile information provided by HF OAuth
  • ✅ Automatic session management

API Keys

  • ⚠️ Store API keys in Space Secrets (not in code)
  • ⚠️ Never commit API keys to repository
  • ⚠️ Use environment variables for all sensitive data

📝 Customer Setup Instructions

Provide these steps to your customers:

For End Users:

  1. Access the Platform:

  2. First Login:

    • You'll see sample data to understand the interface
    • Your personal data directory is automatically created
    • All your data is isolated from other users

  3. Using the Dashboard:

    • Consent/Event Audit: View compliance events
    • Cadence Branching Composer: Design outreach sequences
    • Live Diagnostics: Monitor system health
    • Audit Trail Export: Download compliance reports

  4. Data Refresh:

    • Click "Refresh Data" button in any tab
    • Reloads your latest data from storage

For Administrators:

  1. Access Space settings for configuration
  2. Monitor logs for user activity
  3. Manage Space resources (storage, compute)
  4. Configure API keys for integrations

🐞 Troubleshooting

Issue: "Authentication Required" message persists

Solution:

  • Ensure you've clicked "Sign in with Hugging Face"
  • Check browser cookies are enabled
  • Try hard refresh (Cmd+Shift+R / Ctrl+Shift+R)

Issue: Data not persisting between sessions

Solution:

  • Verify persistent storage is enabled in Space settings
  • Check storage quota hasn't been exceeded
  • Review container logs for write errors

Issue: Space shows "Runtime Error"

Solution:

  1. Click on "Logs" → "Container"
  2. Look for Python errors or exceptions
  3. Check if /data directory is accessible
  4. Verify all dependencies in requirements.txt

Issue: Slow performance

Solution:

  • Upgrade Space hardware tier in Settings
  • Optimize data loading (lazy loading)
  • Implement caching for frequently accessed data

🚀 Next Steps / Future Enhancements

Phase 1: Enhanced Data Management

  • CSV export functionality
  • Data import from external sources
  • Bulk operations for large datasets
  • Data visualization charts

Phase 2: Integration Capabilities

  • Connect actual LinkedIn API
  • Twilio SMS integration
  • Salesforce sync
  • Email campaign management

Phase 3: Advanced Features

  • Team collaboration (share data with team members)
  • Role-based access control
  • Automated backup to cloud storage
  • Advanced analytics dashboard

Phase 4: Enterprise Features

  • SSO integration
  • Compliance certifications (SOC 2, GDPR)
  • White-label branding
  • Custom domain support

📞 Support

For technical support:

  • Documentation: See README.md for API documentation
  • Issues: Report bugs via Hugging Face Space discussions
  • Questions: Contact via Space community tab

🎉 Summary

Your StrategyStack platform is now customer-ready with:

✅ Zero-config deployment - Works out of the box on HF Spaces ✅ Secure authentication - OAuth via Hugging Face ✅ Data privacy - Per-user isolated storage ✅ Multi-tenant - Unlimited users, isolated data ✅ No external dependencies - Everything on HF Spaces ✅ Persistent storage - Data survives restarts ✅ Compliance-ready - Full audit trails

Just enable persistent storage and you're ready to onboard customers!

Last Updated: 2025-01-06 Platform Version: 1.0.0 (OAuth-enabled) Hugging Face Spaces: ✅ Production Ready