Spaces:
Configuration error
Download README.md from StillWorking/lore: direct link, hf CLI and curl.
- Browser
- Download file 6.27 kB
-
https://huggingface.co/spaces/StillWorking/lore/resolve/main/README.md
- Command line
-
hf download hf://spaces/StillWorking/lore/README.md
-
curl -L -o README.md https://huggingface.co/spaces/StillWorking/lore/resolve/main/README.md
Living Lore Board - Backend Deployment Guide
π¦ Deployment Package Contents
This folder contains all files necessary to deploy the Living Lore Board backend to production.
Files Included:
app.py- Main FastAPI application entry pointrequirements.txt- Python dependencies.env.example- Environment variable template (copy to.envand fill in)agents/- LangChain agent modules (lore generation, memory management)ml_pipeline/- ML components (image generation, NLP extraction)Dockerfile- Container configuration for deploymentdocker-compose.yml- Multi-container orchestration (optional)railway.json- Railway.app deployment configurationrender.yaml- Render.com deployment configurationvercel.json- Vercel deployment configurationProcfile- Heroku/generic PaaS configurationgunicorn.conf.py- Production WSGI server configurationnginx.conf- Nginx reverse proxy configuration (for VPS deployment)deploy.sh- Automated deployment scripthealth_check.py- Health monitoring script
π Deployment Options
Option 1: Railway.app (Recommended - Easy & Free Tier)
Install Railway CLI:
npm install -g @railway/cliLogin and initialize:
railway login railway initSet environment variables:
railway variables set GROQ_API_KEY=your_key_here railway variables set GOOGLE_API_KEY=your_key_here railway variables set HF_TOKEN=your_token_here railway variables set HOST=0.0.0.0 railway variables set PORT=8000Deploy:
railway up
Option 2: Render.com (Simple with Auto-Deploy)
- Create a new Web Service on Render.com
- Connect your GitHub repository
- Set Build Command:
pip install -r requirements.txt - Set Start Command:
uvicorn app:app --host 0.0.0.0 --port $PORT - Add environment variables in the Render dashboard
- Deploy automatically on git push
Option 3: Docker (Any Cloud Provider)
Build the image:
docker build -t living-lore-backend .Run the container:
docker run -p 8000:8000 --env-file .env living-lore-backendOr use docker-compose:
docker-compose up -d
Option 4: VPS (DigitalOcean, AWS EC2, etc.)
SSH into your server
Clone/upload this folder
Install dependencies:
python3 -m venv venv source venv/bin/activate pip install -r requirements.txtSet up environment variables:
cp .env.example .env nano .env # Edit with your keysRun with systemd (production):
sudo cp living-lore-backend.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable living-lore-backend sudo systemctl start living-lore-backendConfigure Nginx as reverse proxy:
sudo cp nginx.conf /etc/nginx/sites-available/living-lore-backend sudo ln -s /etc/nginx/sites-available/living-lore-backend /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl restart nginx
Option 5: Vercel (Serverless)
Install Vercel CLI:
npm install -g vercelDeploy:
vercelAdd environment variables via Vercel dashboard
π Environment Variables Required
Copy .env.example to .env and fill in these values:
# Groq API (Primary LLM Engine)
GROQ_API_KEY=your_groq_api_key
# Google Gemini API (Fallback)
GOOGLE_API_KEY=your_google_api_key
# Hugging Face Token (for image generation models)
HF_TOKEN=your_huggingface_token
# Server Configuration
HOST=0.0.0.0
PORT=8000
Getting API Keys:
- Groq API Key: https://console.groq.com/keys
- Google Gemini API: https://aistudio.google.com/app/apikey
- Hugging Face Token: https://huggingface.co/settings/tokens
π Pre-Deployment Checklist
- All environment variables set
- Dependencies installed and tested locally
- API keys are valid and have quota
- CORS origins updated for production domain
- Health endpoint (
/health) returns 200 OK - Test all three endpoints:
- POST
/generate-lore - POST
/generate-avatar - POST
/extract-entities
- POST
π Health Monitoring
After deployment, monitor your service:
# Check health endpoint
curl https://your-domain.com/health
# Run health check script
python health_check.py https://your-domain.com
π Troubleshooting
Issue: Port already in use
Solution: Change PORT in .env or kill existing process
Issue: Import errors
Solution: Ensure all dependencies in requirements.txt are installed
Issue: API key errors
Solution: Verify keys are set correctly in environment variables
Issue: CORS errors
Solution: Update origins list in app.py to include your frontend domain
Issue: Image generation fails
Solution: Uses Pollinations AI (free, no auth), should work by default
π Performance Considerations
- Memory: Minimum 512MB RAM recommended
- CPU: 1 vCPU sufficient for light traffic
- Storage: ~500MB for dependencies
- Network: Image generation requires stable internet
π Security Best Practices
- Never commit
.envfile to version control - Use secrets management for production (AWS Secrets Manager, Railway Variables, etc.)
- Enable HTTPS/SSL certificates (Let's Encrypt recommended)
- Implement rate limiting for API endpoints
- Set up monitoring and alerting
- Regular dependency updates:
pip install --upgrade -r requirements.txt
π Scaling Recommendations
For high traffic:
- Use a production WSGI server (Gunicorn with workers)
- Implement Redis caching for repeated lore generations
- Consider CDN for generated images
- Set up load balancing with multiple instances
- Database integration for persistent memory (currently in-memory)
π Support
For issues or questions:
- Check logs:
railway logsordocker logs living-lore-backend - Review API documentation at
/docsendpoint (FastAPI auto-generates Swagger UI) - Test endpoints individually with Postman or curl
Last Updated: 2026-07-18 Backend Version: 0.1.0