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:

    npm install -g @railway/cli
    
  2. Login and initialize:

    railway login
    railway init
    
  3. Set 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=8000
    
  4. Deploy:

    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:

    docker build -t living-lore-backend .
    
  2. Run the container:

    docker run -p 8000:8000 --env-file .env living-lore-backend
    
  3. Or use docker-compose:

    docker-compose up -d
    

Option 4: VPS (DigitalOcean, AWS EC2, etc.)

  1. SSH into your server

  2. Clone/upload this folder

  3. Install dependencies:

    python3 -m venv venv
    source venv/bin/activate
    pip install -r requirements.txt
    
  4. Set up environment variables:

    cp .env.example .env
    nano .env  # Edit with your keys
    
  5. Run 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-backend
    
  6. Configure 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)

  1. Install Vercel CLI:

    npm install -g vercel
    
  2. Deploy:

    vercel
    
  3. Add 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:

  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:

# 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