Spaces:
Configuration error
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
6.27 kB
| # 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 point | |
| - `requirements.txt` - Python dependencies | |
| - `.env.example` - Environment variable template (copy to `.env` and fill in) | |
| - `agents/` - LangChain agent modules (lore generation, memory management) | |
| - `ml_pipeline/` - ML components (image generation, NLP extraction) | |
| - `Dockerfile` - Container configuration for deployment | |
| - `docker-compose.yml` - Multi-container orchestration (optional) | |
| - `railway.json` - Railway.app deployment configuration | |
| - `render.yaml` - Render.com deployment configuration | |
| - `vercel.json` - Vercel deployment configuration | |
| - `Procfile` - Heroku/generic PaaS configuration | |
| - `gunicorn.conf.py` - Production WSGI server configuration | |
| - `nginx.conf` - Nginx reverse proxy configuration (for VPS deployment) | |
| - `deploy.sh` - Automated deployment script | |
| - `health_check.py` - Health monitoring script | |
| --- | |
| ## π Deployment Options | |
| ### Option 1: Railway.app (Recommended - Easy & Free Tier) | |
| 1. Install Railway CLI: | |
| ```bash | |
| npm install -g @railway/cli | |
| ``` | |
| 2. Login and initialize: | |
| ```bash | |
| railway login | |
| railway init | |
| ``` | |
| 3. Set environment variables: | |
| ```bash | |
| 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=8000 | |
| ``` | |
| 4. Deploy: | |
| ```bash | |
| railway up | |
| ``` | |
| ### Option 2: Render.com (Simple with Auto-Deploy) | |
| 1. Create a new Web Service on Render.com | |
| 2. Connect your GitHub repository | |
| 3. Set Build Command: `pip install -r requirements.txt` | |
| 4. Set Start Command: `uvicorn app:app --host 0.0.0.0 --port $PORT` | |
| 5. Add environment variables in the Render dashboard | |
| 6. Deploy automatically on git push | |
| ### Option 3: Docker (Any Cloud Provider) | |
| 1. Build the image: | |
| ```bash | |
| docker build -t living-lore-backend . | |
| ``` | |
| 2. Run the container: | |
| ```bash | |
| docker run -p 8000:8000 --env-file .env living-lore-backend | |
| ``` | |
| 3. Or use docker-compose: | |
| ```bash | |
| docker-compose up -d | |
| ``` | |
| ### Option 4: VPS (DigitalOcean, AWS EC2, etc.) | |
| 1. SSH into your server | |
| 2. Clone/upload this folder | |
| 3. Install dependencies: | |
| ```bash | |
| python3 -m venv venv | |
| source venv/bin/activate | |
| pip install -r requirements.txt | |
| ``` | |
| 4. Set up environment variables: | |
| ```bash | |
| cp .env.example .env | |
| nano .env # Edit with your keys | |
| ``` | |
| 5. Run with systemd (production): | |
| ```bash | |
| sudo cp living-lore-backend.service /etc/systemd/system/ | |
| sudo systemctl daemon-reload | |
| sudo systemctl enable living-lore-backend | |
| sudo systemctl start living-lore-backend | |
| ``` | |
| 6. Configure Nginx as reverse proxy: | |
| ```bash | |
| 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) | |
| 1. Install Vercel CLI: | |
| ```bash | |
| npm install -g vercel | |
| ``` | |
| 2. Deploy: | |
| ```bash | |
| vercel | |
| ``` | |
| 3. Add environment variables via Vercel dashboard | |
| --- | |
| ## π Environment Variables Required | |
| Copy `.env.example` to `.env` and fill in these values: | |
| ```env | |
| # 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: | |
| 1. **Groq API Key**: https://console.groq.com/keys | |
| 2. **Google Gemini API**: https://aistudio.google.com/app/apikey | |
| 3. **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` | |
| --- | |
| ## π Health Monitoring | |
| After deployment, monitor your service: | |
| ```bash | |
| # 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 | |
| 1. Never commit `.env` file to version control | |
| 2. Use secrets management for production (AWS Secrets Manager, Railway Variables, etc.) | |
| 3. Enable HTTPS/SSL certificates (Let's Encrypt recommended) | |
| 4. Implement rate limiting for API endpoints | |
| 5. Set up monitoring and alerting | |
| 6. Regular dependency updates: `pip install --upgrade -r requirements.txt` | |
| --- | |
| ## π Scaling Recommendations | |
| For high traffic: | |
| 1. Use a production WSGI server (Gunicorn with workers) | |
| 2. Implement Redis caching for repeated lore generations | |
| 3. Consider CDN for generated images | |
| 4. Set up load balancing with multiple instances | |
| 5. Database integration for persistent memory (currently in-memory) | |
| --- | |
| ## π Support | |
| For issues or questions: | |
| - Check logs: `railway logs` or `docker logs living-lore-backend` | |
| - Review API documentation at `/docs` endpoint (FastAPI auto-generates Swagger UI) | |
| - Test endpoints individually with Postman or curl | |
| --- | |
| **Last Updated**: 2026-07-18 | |
| **Backend Version**: 0.1.0 | |