Spaces:
Sleeping
Sleeping
| # 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: | |
| ```python | |
| 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: | |
| ```python | |
| # 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: | |
| ```python | |
| DATA_DIR = Path("/data") # Change if needed | |
| ``` | |
| ### Adding New Data Types | |
| 1. Define new data structure (JSON-serializable) | |
| 2. Use existing functions: | |
| ```python | |
| # Save new data type | |
| save_user_data(username, "campaigns", campaign_data) | |
| # Load new data type | |
| campaigns = load_user_data(username, "campaigns") | |
| ``` | |
| 3. Create UI panel to display/edit | |
| ### Customizing Authentication Messages | |
| Edit the authentication check in panel functions (app.py): | |
| ```python | |
| 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**: | |
| - Visit: https://huggingface.co/spaces/StrategyStack/README | |
| - Click "Sign in with Hugging Face" | |
| - Create free HF account if needed | |
| 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 |