{"id":30232139,"url":"https://github.com/agentmorris/lila-game","last_synced_at":"2025-08-14T23:09:59.789Z","repository":{"id":304752139,"uuid":"1019835208","full_name":"agentmorris/lila-game","owner":"agentmorris","description":"Game in which users guess the species present in camera trap images","archived":false,"fork":false,"pushed_at":"2025-07-15T03:20:21.000Z","size":354,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-15T04:46:49.984Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentmorris.png","metadata":{"files":{"readme":"README-deployment.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T00:36:21.000Z","updated_at":"2025-07-15T03:20:24.000Z","dependencies_parsed_at":"2025-07-15T04:46:56.694Z","dependency_job_id":"09ac5f90-eb6e-4707-8930-4b93bf6331ee","html_url":"https://github.com/agentmorris/lila-game","commit_stats":null,"previous_names":["agentmorris/lila-game"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/agentmorris/lila-game","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentmorris%2Flila-game","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentmorris%2Flila-game/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentmorris%2Flila-game/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentmorris%2Flila-game/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentmorris","download_url":"https://codeload.github.com/agentmorris/lila-game/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentmorris%2Flila-game/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270495127,"owners_count":24593907,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-14T23:09:56.420Z","updated_at":"2025-08-14T23:09:59.777Z","avatar_url":"https://github.com/agentmorris.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The LILA Game - Deployment Guide\n\nA web-based wildlife camera trap identification game using real camera trap images from conservation research projects.\n\n## Project Overview\n\nThis app provides an educational wildlife identification game where players view sequences of camera trap images and identify animals at various taxonomic levels. Players earn points based on the accuracy of their identification, from species (10 points) to family (3 points) to order (1 point).\n\n**Tech Stack:**\n- Backend: Flask with SQLite database\n- Frontend: HTML/CSS/JavaScript (vanilla, no frameworks)\n- LLM: Google Gemini API for hints and fun facts\n- Deployment: Docker container with volume persistence\n- Database: SQLite with camera trap image metadata\n\n## Features\n\n- **Real camera trap sequences** from wildlife research projects\n- **Hierarchical scoring system** rewarding taxonomic accuracy\n- **AI-powered hints** using Gemini API (without revealing answers)\n- **Fun facts** about correctly identified animals\n- **Autocomplete search** supporting scientific and common names\n- **High score leaderboard** with persistent storage\n- **Responsive interface** optimized for wildlife learning\n\n## Project Structure\n\n```\nlila-game/\n├── app.py                    # Main Flask application\n├── models.py                 # Database models and queries\n├── game_logic.py             # Game mechanics, scoring, and AI features\n├── db_setup.py               # Database schema creation\n├── data_processor.py         # CSV to database import tool\n├── templates/                # HTML templates\n│   ├── base.html\n│   ├── index.html\n│   ├── question.html\n│   └── high_scores.html\n├── static/                   # CSS and JavaScript\n│   └── style.css\n├── data/                     # Docker volume mount point\n├── requirements.txt          # Python dependencies\n├── Dockerfile               # Docker configuration\n├── docker-compose.yml      # Docker Compose setup\n├── .env.example            # Environment variables template\n└── README.md               # Main documentation\n```\n\n## Setup Instructions\n\n### Local Development (Recommended for Testing)\n\n1. **Clone/Setup the project directory:**\n   ```bash\n   cd lila-game\n   ```\n\n2. **Create a virtual environment:**\n   ```bash\n   python -m venv venv\n   # On Linux/WSL:\n   source venv/bin/activate\n   # On Windows Command Prompt:\n   # venv\\Scripts\\activate\n   ```\n\n3. **Install dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. **Set up database:**\n   ```bash\n   # Initialize database schema\n   python db_setup.py\n   \n   # Import your camera trap CSV data\n   python data_processor.py --csv-path /path/to/your/camera-trap-data.csv\n   ```\n\n5. **Set up environment variables (optional):**\n   ```bash\n   cp .env.example .env\n   # Edit .env and add your Gemini API key for AI features\n   ```\n\n6. **Run the application:**\n   ```bash\n   python app.py\n   ```\n\n7. **Access the app:**\n   Open your browser to `http://localhost:5001`\n\n### Docker Deployment\n\n1. **Prepare data directory:**\n   ```bash\n   mkdir -p data\n   # Copy your existing database file to data directory\n   cp camera_trap_data.db data/\n   ```\n\n2. **Set up configuration:**\n   ```bash\n   cp .env.example .env\n   # Edit .env and add your Gemini API key\n   \n   # Optional: Configure Gemini model\n   echo \"gemini-1.5-flash\" \u003e .gemini-config\n   ```\n\n3. **Build and run with Docker Compose:**\n   ```bash\n   docker-compose up --build\n   ```\n\n4. **Access the app:**\n   Open your browser to `http://your-hostname:5001` or `http://your-ip:5001`\n\n### Production Deployment\n\nFor production deployment on your Ubuntu VM:\n\n1. **Copy files to your server**\n2. **Set up environment and database**\n3. **Run with Docker Compose:**\n   ```bash\n   docker-compose up -d\n   ```\n\nThe app will be available at `your-hostname.com:5001` alongside your existing Apache setup.\n\n## Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```env\n# Gemini API Configuration (optional, for AI features)\nGEMINI_API_KEY=your_gemini_api_key_here\nGEMINI_MODEL_NAME=gemini-1.5-flash\n\n# Flask Configuration\nPORT=5001\nFLASK_ENV=production\n\n# Game Configuration (optional)\nQUESTIONS_PER_GAME=10\nSEQUENCES_PER_QUESTION=4\nIMAGE_CLOUD_PREFERENCE=gcp\n\n# Proxy Configuration (for Apache reverse proxy deployment)\nAPPLICATION_ROOT=/\n\n# Debugging Configuration (for development)\nDISABLE_AI=false\n\n# Database Configuration (optional)\nDATABASE_PATH=/app/data/camera_trap_data.db\n```\n\n## AI Features Setup (Optional)\n\nFor hints and fun facts features:\n\n1. **Get Gemini API key** from [Google AI Studio](https://makersuite.google.com/app/apikey)\n\n2. **Provide the API key** using one of these methods (in order of priority):\n\n   **Option A: Environment Variable**\n   ```bash\n   export GEMINI_API_KEY=\"your-api-key-here\"\n   ```\n\n   **Option B: .env File**\n   Create a `.env` file in the project root:\n   ```\n   GEMINI_API_KEY=your-api-key-here\n   ```\n\n   **Option C: .gemini-key File**\n   Create a `.gemini-key` file in the project root:\n   ```\n   your-api-key-here\n   ```\n\n3. **Configure model (optional):**\n   Create a `.gemini-config` file:\n   ```\n   gemini-1.5-flash\n   ```\n   \n   Available models: `gemini-1.5-flash` (fast), `gemini-1.5-pro` (balanced), `gemini-2.5-pro` (advanced)\n\n4. **Restart the application** - AI features will now be available\n\n## Deployment\n\n### Ubuntu Linux Server Deployment\n\n#### Prerequisites\n\n1. **Install Docker and Docker Compose on Ubuntu:**\n   ```bash\n   # Update package index\n   sudo apt update\n   \n   # Install Docker\n   sudo apt install -y docker.io docker-compose\n   \n   # Start and enable Docker\n   sudo systemctl start docker\n   sudo systemctl enable docker\n   \n   # Add your user to docker group (logout/login required)\n   sudo usermod -aG docker $USER\n   ```\n\n2. **Open required ports:**\n   ```bash\n   # Open port 5001 (or your chosen port) in UFW firewall\n   sudo ufw allow 5001\n   \n   # If using iptables instead:\n   sudo iptables -A INPUT -p tcp --dport 5001 -j ACCEPT\n   ```\n\n#### Deployment Steps\n\n1. **Copy project files to your server:**\n   ```bash\n   # Using scp from your local machine:\n   scp -r lila-game/ user@your-server-ip:/home/user/\n   \n   # Or clone if using git:\n   git clone your-repo-url lila-game\n   cd lila-game\n   ```\n\n2. **Set up database and configuration:**\n   ```bash\n   # Ensure data directory exists\n   mkdir -p data\n   \n   # Copy your populated database if you have one\n   cp camera_trap_data.db data/\n   \n   # Set up environment variables\n   cp .env.example .env\n   nano .env  # Add your Gemini API key\n   \n   # Optional: Set up Gemini model preference\n   echo \"gemini-1.5-flash\" \u003e .gemini-config\n   ```\n\n3. **Deploy with Docker:**\n   ```bash\n   # Build and start the application\n   docker-compose up -d --build\n   \n   # View logs to ensure it's running\n   docker-compose logs -f\n   ```\n\n4. **Verify deployment:**\n   ```bash\n   # Check if the container is running\n   docker-compose ps\n   \n   # Test the application\n   curl http://localhost:5001/\n   \n   # Or test from another machine\n   curl http://your-server-ip:5001/\n   ```\n\n5. **Access your application:**\n   - Local: `http://your-server-ip:5001`\n   - Domain: `http://yourdomain.com:5001`\n\n#### Managing the Deployment\n\n**Stop the application:**\n```bash\ndocker-compose down\n```\n\n**Update and restart:**\n```bash\n# Pull latest changes (if using git)\ngit pull\n\n# Rebuild and restart\ndocker-compose down\ndocker-compose up -d --build\n```\n\n**View logs:**\n```bash\n# View current logs\ndocker-compose logs\n\n# Follow logs in real-time\ndocker-compose logs -f\n```\n\n**Change the port:**\nEdit `docker-compose.yml` and change the port mapping:\n```yaml\nports:\n  - \"5002:5001\"  # This would make it accessible on port 5002\n```\n\n**Database management:**\n```bash\n# Access the database directly\ndocker-compose exec lila-game sqlite3 /app/data/camera_trap_data.db\n\n# Backup the database\ndocker-compose exec lila-game cp /app/data/camera_trap_data.db /app/data/backup-$(date +%Y%m%d).db\n\n# Clear high scores (for testing/reset)\nsqlite3 data/camera_trap_data.db \"DELETE FROM high_scores;\"\n\n# View current high scores\nsqlite3 data/camera_trap_data.db \"SELECT player_name, score, game_date FROM high_scores ORDER BY score DESC;\"\n\n# Check database stats\nsqlite3 data/camera_trap_data.db \"SELECT COUNT(*) as taxa_count FROM taxa; SELECT COUNT(*) as scores_count FROM high_scores;\"\n```\n\n#### Running alongside Apache\n\nSince you mentioned Apache is already running on your server:\n\n1. **The app runs on port 5001 by default** (separate from Apache's 80/443)\n2. **Users access it directly**: `yourdomain.com:5001`\n3. **Set up Apache reverse proxy** to serve it on a subdirectory path:\n\n   **Option A: Subdirectory Path (Recommended)**\n   ```apache\n   # In your existing Apache virtual host config\n   \u003cVirtualHost *:80\u003e\n       ServerName yourdomain.com\n       \n       # Your existing configuration...\n       \n       # LILA Game proxy\n       ProxyPass /lila-game http://localhost:5001/\n       ProxyPassReverse /lila-game http://localhost:5001/\n       ProxyPreserveHost On\n   \u003c/VirtualHost\u003e\n   ```\n   \n   **Configure APPLICATION_ROOT for subdirectory deployment:**\n   ```bash\n   # In your .env file:\n   APPLICATION_ROOT=/lila-game\n   ```\n   \n   **Access:** `yourdomain.com/lila-game`\n\n   **Option B: Subdomain**\n   ```apache\n   # Separate virtual host for subdomain\n   \u003cVirtualHost *:80\u003e\n       ServerName lila-game.yourdomain.com\n       ProxyPass / http://localhost:5001/\n       ProxyPassReverse / http://localhost:5001/\n       ProxyPreserveHost On\n   \u003c/VirtualHost\u003e\n   ```\n   \n   **Configure APPLICATION_ROOT for subdomain deployment:**\n   ```bash\n   # In your .env file:\n   APPLICATION_ROOT=/\n   ```\n   \n   **Access:** `lila-game.yourdomain.com`\n\n#### APPLICATION_ROOT Configuration\n\nThe `APPLICATION_ROOT` setting is crucial for proper asset loading when using Apache reverse proxy:\n\n**For direct access (yourdomain.com:5001):**\n```env\nAPPLICATION_ROOT=/\n```\n\n**For subdirectory proxy (yourdomain.com/lila-game):**\n```env\nAPPLICATION_ROOT=/lila-game\n```\n\n**For subdomain proxy (lila-game.yourdomain.com):**\n```env\nAPPLICATION_ROOT=/\n```\n\nThis setting ensures that CSS files, JavaScript files, and AJAX requests use the correct paths when accessed through the Apache proxy.\n\n#### Troubleshooting\n\n**Port already in use:**\n```bash\n# Check what's using port 5001\nsudo netstat -tlnp | grep :5001\n\n# Change port in docker-compose.yml if needed\n```\n\n**Database issues:**\n```bash\n# Check if database file exists and is readable\ndocker-compose exec lila-game ls -la /app/data/\n\n# Check database contents\ndocker-compose exec lila-game sqlite3 /app/data/camera_trap_data.db \"SELECT COUNT(*) FROM taxa;\"\n```\n\n**AI features not working:**\n```bash\n# Check API key configuration\ndocker-compose exec lila-game cat /app/.gemini-key\n\n# Check logs for API errors\ndocker-compose logs | grep -i gemini\n```\n\n**Container won't start:**\n```bash\n# Check detailed logs\ndocker-compose logs lila-game\n\n# Check container status\ndocker-compose ps\n```\n\n## Data Management\n\n### Importing New Camera Trap Data\n\n1. **Prepare your CSV file** with camera trap data\n2. **Copy to container:**\n   ```bash\n   # Copy CSV to data directory\n   cp your-new-data.csv data/\n   \n   # Process the data\n   docker-compose exec lila-game python data_processor.py --csv-path /app/data/your-new-data.csv\n   ```\n\n### Database Maintenance\n\n```bash\n# Check database size\ndocker-compose exec lila-game ls -lh /app/data/camera_trap_data.db\n\n# Vacuum database (reclaim space)\ndocker-compose exec lila-game sqlite3 /app/data/camera_trap_data.db \"VACUUM;\"\n\n# Check database integrity\ndocker-compose exec lila-game sqlite3 /app/data/camera_trap_data.db \"PRAGMA integrity_check;\"\n```\n\n## Customization\n\n### Changing Game Configuration\n\nEdit `.env` file:\n```env\nQUESTIONS_PER_GAME=15          # More questions per game\nSEQUENCES_PER_QUESTION=6       # More image sequences per question\nIMAGE_CLOUD_PREFERENCE=aws     # Prefer AWS images over GCP\n```\n\n### Modifying AI Behavior\n\n1. **Switch to faster model**: Edit `.gemini-config` to use `gemini-1.5-flash`\n2. **Adjust prompts**: Edit `game_logic.py` functions `get_hint()` and `get_fun_fact()`\n3. **Change timeout**: Modify timeout values in API calls (currently 20 seconds)\n\n### Styling Changes\n\nModify `static/style.css` to change the appearance of the game interface.\n\n## Monitoring\n\n### Application Health\n\n```bash\n# Check if application is responding\ncurl http://localhost:5001/\n\n# Monitor resource usage\ndocker-compose exec lila-game top\n\n# Check disk usage\ndocker-compose exec lila-game df -h\n```\n\n### Log Analysis\n\n```bash\n# Search for errors\ndocker-compose logs | grep -i error\n\n# Monitor AI API calls\ndocker-compose logs | grep -i \"DEBUG.*gemini\"\n\n# Check game activity\ndocker-compose logs | grep -i \"new game\\|submit_answer\"\n```\n\n## Performance Optimization\n\n### Database Performance\n\nFor large databases (\u003e1GB):\n```bash\n# Increase SQLite cache size (edit models.py)\n# Add indexes for slow queries\n# Consider splitting very large datasets\n```\n\n### AI API Performance\n\n```bash\n# Use faster model for better response times\necho \"gemini-1.5-flash\" \u003e .gemini-config\n\n# Monitor API response times in logs\ndocker-compose logs | grep \"API response status\"\n```\n\n## Backup and Recovery\n\n### Backup Strategy\n\n```bash\n#!/bin/bash\n# Daily backup script\nDATE=$(date +%Y%m%d)\ndocker-compose exec lila-game cp /app/data/camera_trap_data.db /app/data/backup-$DATE.db\n```\n\n### Recovery\n\n```bash\n# Restore from backup\ncp data/backup-YYYYMMDD.db data/camera_trap_data.db\ndocker-compose restart\n```\n\n## Future Enhancements\n\nPotential features to add:\n- **User accounts** with personal statistics\n- **Multiple difficulty levels** (species-only vs all levels)\n- **Geographic filtering** by region/continent\n- **Seasonal challenges** with themed content\n- **Educational mode** with immediate answer reveals\n- **Mobile app** version with offline capability\n\n## Support\n\nThis deployment follows the same pattern as your successful NFL chatbot deployment. The codebase is designed to be simple and maintainable while providing robust wildlife education features.\n\nFor issues specific to camera trap data or large databases, most problems relate to CSV format compatibility or database size management during import.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentmorris%2Flila-game","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentmorris%2Flila-game","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentmorris%2Flila-game/lists"}