SETUP_INSTRUCTIONS.md

Security Setup Instructions

Summary

All security improvements have been successfully committed and pushed to GitHub. Follow the instructions below to complete the deployment to HuggingFace and set up your environment variables.

What Was Fixed

Security Improvements ✅

• Removed hardcoded ADMIN123 token (now environment-based with auto-generation)
• Rotated Flask secret key with fail-fast validation
• Added rate limiting to authentication endpoints
• Removed exposed HuggingFace token from git config
• Created comprehensive SECURITY.md documentation

HuggingFace Deployment Fixes ✅

• Fixed TRANSFORMERS_CACHE deprecation warning
• Resolved matplotlib permission errors
• Improved SQLite database locking issues
• Fixed sentence text display in PDF exports

---

Step 1: Push to HuggingFace

Since you revoked the old HuggingFace token, you need to authenticate with your new token:

cd /home/thadillo/MyProjects/participatory_planner

# Push to HuggingFace (you'll be prompted for credentials)
git push hf feature/sentence-level-categorization:main

When prompted:

• Username: thadillo
• Password: Enter your NEW HuggingFace write token (starts with hf_...)

The credentials will be stored in git credential helper for future pushes.

---

Step 2: Configure HuggingFace Spaces Secrets

Go to your HuggingFace Space settings and add these Repository Secrets:

https://huggingface.co/spaces/thadillo/participatory-planner/settings

Required Secrets:

1. FLASK_SECRET_KEY (Critical - for session security)

   Generate a new one with:
   python -c "import secrets; print(secrets.token_hex(32))"
   
   Example output (DO NOT USE THIS - generate your own):
   c5eafdcbd348d3176bf1fcf52d90357575f7bc1986b7baeb67bb9d140f401881
   

2. ADMIN_TOKEN (Critical - for admin access)

   Generate a new one with:
   python -c "import secrets; print(secrets.token_urlsafe(16))"
   
   Example output (DO NOT USE THIS - generate your own):
   xulmKoajFS07akF9Eos9Tg
   

   SAVE THIS TOKEN SECURELY - You'll need it to log in to the admin panel!

How to Add Secrets in HuggingFace:

1. Go to your Space: https://huggingface.co/spaces/thadillo/participatory-planner
2. Click Settings tab
3. Scroll to Repository Secrets section
4. Click New Secret
5. Add each secret:
   • Name: FLASK_SECRET_KEY
   • Value: (paste the generated secret key)
   • Click Add
6. Repeat for ADMIN_TOKEN

---

Step 3: Configure Local Development Environment

Update your local .env file with the SAME values you set in HuggingFace:

cd /home/thadillo/MyProjects/participatory_planner

# Edit your .env file
nano .env

Your .env file should contain:

# Flask Configuration
FLASK_SECRET_KEY=<PASTE THE SAME VALUE YOU USED IN HUGGINGFACE>
FLASK_ENV=development

# Model Configuration
MODELS_DIR=models/finetuned
CUDA_VISIBLE_DEVICES=-1

# Admin Token (must match HuggingFace secret)
ADMIN_TOKEN=<PASTE THE SAME VALUE YOU USED IN HUGGINGFACE>

Important: Use the EXACT SAME values for FLASK_SECRET_KEY and ADMIN_TOKEN that you set in HuggingFace. This ensures your local environment matches production.

---

Step 4: Verify Local Setup

Test that your local environment works correctly:

cd /home/thadillo/MyProjects/participatory_planner

# Start the application
./start.sh

You should see output like:

🔐 Admin token: Check startup logs or set ADMIN_TOKEN in .env
🚀 Starting application...

If you didn't set ADMIN_TOKEN in .env, a random token will be generated and displayed ONCE in the logs. Save it immediately!

---

Step 5: Test Admin Access

Local Testing:

1. Start the application: ./start.sh
2. Go to: http://localhost:5000/generate
3. Generate a new token using your ADMIN_TOKEN
4. Use the generated token to test the application

HuggingFace Testing:

1. Wait for HuggingFace to rebuild (after pushing changes)
2. Go to: https://thadillo-participatory-planner.hf.space/generate
3. Generate a new token using your ADMIN_TOKEN
4. Verify the application works without the previous errors

---

Step 6: Verify HuggingFace Deployment

After pushing to HuggingFace, monitor the build logs:

https://huggingface.co/spaces/thadillo/participatory-planner/logs

Check for these confirmations:

1. ✅ No TRANSFORMERS_CACHE deprecation warning
2. ✅ No matplotlib permission errors
3. ✅ No SQLite database locking errors
4. ✅ Application starts successfully

---

Security Best Practices Going Forward

DO:

✅ Keep .env file local and never commit it to git ✅ Use different secrets for development and production ✅ Rotate secrets periodically (every 3-6 months) ✅ Store production secrets only in HuggingFace Spaces secrets ✅ Use strong, randomly generated tokens (via secrets module)

DON'T:

❌ Never commit .env to git ❌ Never hardcode secrets in code ❌ Never share your ADMIN_TOKEN publicly ❌ Never use simple passwords like "ADMIN123" ❌ Never include tokens in git remote URLs

---

Quick Reference Commands

Generate Flask Secret Key:

python -c "import secrets; print(secrets.token_hex(32))"

Generate Admin Token:

python -c "import secrets; print(secrets.token_urlsafe(16))"

Push to HuggingFace:

git push hf feature/sentence-level-categorization:main

Start Local Server:

./start.sh

View HuggingFace Logs:

https://huggingface.co/spaces/thadillo/participatory-planner/logs

View HuggingFace Settings:

https://huggingface.co/spaces/thadillo/participatory-planner/settings

---

Troubleshooting

If HuggingFace deployment fails:

1. Check the build logs for error messages
2. Verify all secrets are set correctly in HuggingFace settings
3. Ensure FLASK_SECRET_KEY and ADMIN_TOKEN are set

If you get "database is locked" errors:

• The new retry logic should handle this automatically
• If it persists, check HuggingFace logs for concurrent request issues

If you forget your ADMIN_TOKEN:

1. Generate a new one: python -c "import secrets; print(secrets.token_urlsafe(16))"
2. Update it in HuggingFace Spaces secrets
3. Update it in your local .env file
4. Restart the application

If authentication fails:

• Ensure you're using the correct ADMIN_TOKEN
• Check that rate limiting hasn't blocked you (wait 1 hour)
• Verify the token in HuggingFace secrets matches your local .env

---

Next Steps

1. Immediate: Push to HuggingFace using the command above
2. Immediate: Set up HuggingFace Spaces secrets (FLASK_SECRET_KEY, ADMIN_TOKEN)
3. Immediate: Update your local .env file
4. Soon: Test the application on HuggingFace to verify all errors are resolved
5. Optional: Consider merging feature/sentence-level-categorization to main branch

---

Files Modified

All changes have been committed to git. Here's what was changed:

• app/init.py - Secure token generation, secret key validation, rate limiter
• app/routes/auth.py - Rate limiting on login/generate endpoints
• app/routes/admin.py - Removed hardcoded ADMIN123 references
• requirements.txt - Added Flask-Limiter
• .env.example - Updated with new structure
• Dockerfile - Fixed HuggingFace deployment issues
• SECURITY.md - New comprehensive security documentation
• Multiple markdown files - Documentation cleanup

---

Support

For questions or issues:

• Review SECURITY.md for detailed security information
• Check HuggingFace build logs for deployment errors
• Verify environment variables are set correctly

Remember: Save your ADMIN_TOKEN securely - it's shown only once when auto-generated!