Hit The Grounds Bot 🏏

A complete, containerizable Python application for managing photo submissions via Telegram for LED wall display at cricket match events. Built with FastAPI, aiogram, SQLAlchemy, and real-time WebSocket updates.

Features

📸 Telegram Bot

• Photo Submissions: Users send photos directly via Telegram
• Auto Queue Management: Photos are queued for admin approval
• Rate Limiting: 1 photo per user per 30 minutes to prevent spam
• Smart Queue Control: Automatic slow mode when queue is full (>10 pending)
• User Notifications: Automatic approval/scheduling notifications sent back to users

🔐 Admin Panel

• Web Interface: Beautiful admin dashboard at /admin
• HTTP Basic Auth: Simple username/password authentication
• Pending Queue: Visual grid of all pending submissions with image previews
• One-Click Actions: Approve or reject with a single click
• Recent History: View recently approved submissions

📺 LED Wall Display

• Full-Screen Display: Dedicated display page at /display
• Real-Time Updates: WebSocket-powered automatic image updates
• Auto-Scheduling: Approved images automatically scheduled (60s intervals)
• Smooth Transitions: Beautiful fade-in animations

🔄 Background Processing

• APScheduler: Automatic scheduling of approved images
• Queue Management: Smart scheduling based on queue status
• WebSocket Broadcasting: Real-time updates to all connected displays

Architecture

┌─────────────────┐
│  Telegram Bot   │ ──► Photo Submissions
│    (aiogram)    │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│   SQLite DB     │ ──► Queue Storage
│  (SQLAlchemy)   │
└─────────────────┘
         │
         ▼
┌─────────────────┐
│ APScheduler     │ ──► Auto-Scheduling
│  Background     │
└─────────────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│  Admin Panel    │     │  LED Display    │
│   (FastAPI)     │     │  (WebSocket)    │
└─────────────────┘     └─────────────────┘

Quick Start

Prerequisites

• Docker and Docker Compose
• Telegram Bot Token (get from @BotFather)
• Domain with Nginx configured (for production)

Using Pre-built Image from GHCR

Pull and run the latest image:

docker pull ghcr.io/cse23-mora/hit-the-grounds-bot:latest

# Or use docker-compose with the pre-built image
# Update docker-compose.yml to use:
# image: ghcr.io/cse23-mora/hit-the-grounds-bot:latest
# instead of build: .

1. Clone and Configure

git clone <repository-url>
cd "Hit The Grounds Bot"

# Copy environment template
cp .env.example .env

# Edit .env and add your Telegram bot token
nano .env

2. Update Environment Variables

Edit .env file:

# REQUIRED: Get from @BotFather on Telegram
BOT_TOKEN=your_telegram_bot_token_here

# Admin credentials for web panel
ADMIN_USER=admin
ADMIN_PASS=your_secure_password

# Your domain (for image URLs)
DOMAIN=https://yourdomain.com

3. Run with Docker Compose

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

The application will be available at:

• API: http://localhost:8000
• Admin Panel: http://localhost:8000/admin
• Display: http://localhost:8000/display

Production Deployment

1. Set Up Nginx

Copy the sample Nginx configuration:

sudo cp docs/nginx.conf /etc/nginx/sites-available/hitthegrounds
sudo ln -s /etc/nginx/sites-available/hitthegrounds /etc/nginx/sites-enabled/

Edit /etc/nginx/sites-available/hitthegrounds:

• Replace yourdomain.com with your actual domain
• Update SSL certificate paths
• Update alias /path/to/hit-the-grounds-bot/data/images/ with actual path

2. Obtain SSL Certificate

# Using certbot (Let's Encrypt)
sudo certbot --nginx -d yourdomain.com

3. Create Data Directories

mkdir -p data/images
touch data/db.sqlite
chmod 777 data/images  # Ensure Docker can write

4. Update docker-compose.yml

In production, you may want to:

• Use an external network
• Add restart policies
• Configure resource limits

5. Test Nginx Configuration

sudo nginx -t
sudo systemctl reload nginx

Configuration

Environment Variables

Variable	Default	Description
BOT_TOKEN	-	Required Telegram bot token
ADMIN_USER	admin	Admin username
ADMIN_PASS	changeme	Admin password
DB_PATH	/app/db.sqlite	Database file path
IMAGES_PATH	/app/images	Images storage path
DOMAIN	https://yourdomain.com	Base URL for images
LOG_LEVEL	INFO	Logging level
RATE_LIMIT_MINUTES	30	Minutes between submissions per user
QUEUE_FULL_THRESHOLD	10	Queue size to trigger slow mode
QUEUE_RESUME_THRESHOLD	5	Queue size to resume submissions
DISPLAY_INTERVAL_SECONDS	60	Seconds between scheduled images

API Endpoints

• GET / - API information
• GET /health - Health check
• GET /admin - Admin panel (auth required)
• POST /admin/approve/{id} - Approve submission
• POST /admin/reject/{id} - Reject submission
• GET /display - Display page
• WS /ws/display - WebSocket for real-time updates

Database Schema

Submissions Table

• id - Primary key
• user_id - Telegram user ID
• username - Telegram username
• image_path - Relative path to image
• submitted_timestamp - When submitted
• approval_status - PENDING | APPROVED | REJECTED
• scheduled_time - When to display (null until approved)

Current Display Table

• id - Always 1 (singleton)
• submission_id - Current submission being displayed
• image_path - Path to current image
• display_timestamp - When it started displaying

CI/CD with GitHub Actions

The project includes a GitHub Actions workflow that automatically builds and pushes Docker images to GitHub Container Registry (GHCR).

Automatic Builds

Images are automatically built and pushed on:

• Push to main/master branch: Tagged as latest
• Version tags (e.g., v1.0.0): Tagged with version numbers
• Pull requests: Built but not pushed (for testing)

Multi-Platform Support

The workflow builds for both:

• linux/amd64 (x86_64)
• linux/arm64 (ARM64/aarch64)

Using the Pre-built Image

Update your docker-compose.yml:

services:
  hit-the-grounds-bot:
    image: ghcr.io/cse23-mora/hit-the-grounds-bot:latest
    # Remove the 'build: .' line
    container_name: hit-the-grounds-bot
    # ... rest of configuration

Development

Local Development (without Docker)

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp .env.example .env

# Run migrations
alembic upgrade head

# Start application
python main.py

Running Tests

pytest tests/

Database Migrations

# Create a new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

Troubleshooting

Bot Not Responding

• Check BOT_TOKEN is correct
• Verify bot is not blocked
• Check logs: docker-compose logs -f

Images Not Loading

• Verify Nginx configuration
• Check DOMAIN environment variable
• Ensure images directory is mounted correctly
• Check file permissions on data/images/

WebSocket Connection Failed

• Ensure Nginx has WebSocket support configured
• Check firewall allows WebSocket connections
• Verify wss:// (SSL) vs ws:// protocol

Database Locked Errors

• Ensure only one instance is running
• Check file permissions on db.sqlite
• SQLite doesn't support high concurrency; consider PostgreSQL for production

Security Considerations

• Change default ADMIN_PASS immediately
• Use strong passwords
• Enable HTTPS (never run without SSL in production)
• Keep Telegram BOT_TOKEN secret
• Regularly update dependencies
• Consider implementing rate limiting on web endpoints
• Review and sanitize user-uploaded images

License

MIT License - feel free to use for your events!

Support

For issues, questions, or contributions, please open an issue on GitHub.

Acknowledgments

Built with:

• FastAPI - Modern web framework
• aiogram - Telegram Bot framework
• SQLAlchemy - Database ORM
• APScheduler - Background scheduling
• Alembic - Database migrations

---

Made with ❤️ for cricket fans 🏏