lore / README.md
StillWorking's picture
Upload 16 files
a387ea0 verified
|
Raw History Blame Contribute Delete
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