Discord Hackathon Bot 🤖

A production-ready Discord bot that automatically discovers, scrapes, and notifies about hackathons from multiple platforms. Built with Python and discord.py 2.x, featuring your integrated scraper repository for Devpost, AllHackathons, and Hack2Skill.

🎯 Features

🔍 Hackathon Discovery

• Multi-platform scraping: Devpost, AllHackathons, Hack2Skill
• Smart filtering: By website, mode (online/offline/hybrid), prizes
• Advanced search: Text search across names, tags, locations
• Real-time updates: Automatic scraping on configurable schedules

📢 Notifications

• Automatic alerts: New hackathons posted to configured channels
• Duplicate prevention: Smart deduplication prevents repeat notifications
• Rich embeds: Beautiful Discord embeds with all hackathon details

🛠️ Administration

• Slash commands: Modern Discord slash command interface
• Permission system: Admin-only commands with proper access control
• Monitoring: Comprehensive status dashboards and logging
• Background tasks: Automatic scraping and notification posting

🚀 Quick Start

Prerequisites

• Python 3.10+
• Discord Bot Token
• MongoDB database
• Chrome/Chromium (for scraping)

1. Clone and Setup

git clone <your-repo>
cd discord-hackathon-bot

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
nano .env

2. Install Dependencies

pip install -r requirements.txt

3. Configure Environment

Edit .env file with your settings:

# Required
DISCORD_BOT_TOKEN=your_bot_token_here
MONGO_URI=mongodb://localhost:27017/HackBot

# Optional
BOT_OWNER_ID=your_discord_user_id
SCRAPE_EVERY_HOURS=6
POST_POLL_MINUTES=30

4. Run the Bot

python -m bot.main

🐳 Docker Deployment

Using Docker Compose (Recommended)

# Start with included MongoDB
docker-compose up -d

# Or with external MongoDB
docker-compose up -d hackbot

Using Docker Only

# Build image
docker build -t hackathon-bot .

# Run container
docker run -d \
  --name hackathon-bot \
  --env-file .env \
  -v $(pwd)/bot/data:/home/hackbot/bot/data \
  hackathon-bot

☁️ Cloud Platform Deployment

Railway

1. Fork this repository
2. Connect to Railway
3. Add environment variables
4. Deploy automatically

Render

1. Create new Web Service
2. Connect repository
3. Set build command: pip install -r requirements.txt
4. Set start command: python -m bot.main
5. Add environment variables

Heroku

# Install Heroku CLI and login
heroku create your-bot-name

# Add buildpacks for Chrome
heroku buildpacks:add --index 1 heroku/python
heroku buildpacks:add --index 2 https://github.com/heroku/heroku-buildpack-google-chrome
heroku buildpacks:add --index 3 https://github.com/heroku/heroku-buildpack-chromedriver

# Set environment variables
heroku config:set DISCORD_BOT_TOKEN=your_token
heroku config:set MONGO_URI=your_mongodb_uri

# Deploy
git push heroku main

🎮 Bot Commands

Hackathon Commands (/hack)

• /hack latest - Get latest hackathons with filtering options
• /hack search <query> - Search hackathons by keywords
• /hack scrape <site> - Trigger manual scraping
• /hack stats - Show database statistics

Notification Commands (/notify)

• /notify set <channel> - Set up automatic notifications
• /notify unsub - Disable notifications
• /notify status - Show notification settings

Admin Commands (/admin)

• /admin sync - Sync slash commands
• /admin status - Comprehensive bot status
• /admin cleanup - Clean old tracking data
• /admin reset - Reset tracking data
• /admin scheduler - Background task status

🔧 Configuration

Environment Variables

Variable	Required	Default	Description
DISCORD_BOT_TOKEN	✅	-	Discord bot token
MONGO_URI	✅	-	MongoDB connection string
BOT_OWNER_ID	❌	-	Discord user ID for admin access
GUILD_ID	❌	-	Guild ID for faster command sync (dev)
SCRAPE_EVERY_HOURS	❌	6	Auto-scraping interval
POST_POLL_MINUTES	❌	30	Notification polling interval

Owner & Admin Access (Important)

The /hack scrape command is resource intensive and should be restricted. The bot supports two ways to allow users to run this command:

• BOT owner (single user): set BOT_OWNER_ID to your Discord user ID (snowflake). This user will always be allowed to run admin commands.
• Administrator permission flag: users with Discord's built-in Administrator permission are allowed.
• Role name fallback: set ADMIN_ROLE_NAME (default Admin) to a role name in your guild; members with that role will be allowed as a fallback.

Recommended configuration (safer): use BOT_OWNER_ID plus role IDs rather than role names. Role names can be renamed by server admins and are case-sensitive. To use role IDs, update the bot code to read an env var like ADMIN_ROLE_IDS (comma-separated IDs) — ask me and I can add it.

Example .env additions:

# Make yourself the bot owner (replace with your Discord user ID)
BOT_OWNER_ID=123456789012345678

# Optional: fallback role name allowed to run /hack scrape
ADMIN_ROLE_NAME=Admin

MongoDB Setup

The bot requires a MongoDB database with the following structure:

• Database: HackBot
• Collection: Hackathons

Sample Document:

{
  "name": "Example Hackathon 2024",
  "url": "https://example.com/hackathon",
  "image": "https://example.com/image.jpg",
  "start": "2024-03-01",
  "end": "2024-03-03",
  "mode": "Virtual",
  "location": "Online",
  "website": "DEVPOST",
  "new": true,
  "prize_amount": "$10,000",
  "participants": "500+",
  "tags": ["AI", "Web Development"],
  "timeline": "March 1-3, 2024",
  "deadline": "March 1, 2024"
}

🤖 Discord Bot Setup

1. Create Discord Application

1. Go to Discord Developer Portal
2. Click "New Application"
3. Name your bot and save

2. Create Bot User

1. Go to "Bot" section
2. Click "Add Bot"
3. Copy the token (keep it secret!)

3. Set Bot Permissions

Required permissions:

• Send Messages
• Use Slash Commands
• Embed Links
• Read Message History

4. Invite Bot to Server

Use this URL template:

https://discord.com/api/oauth2/authorize?client_id=YOUR_BOT_ID&permissions=2147483648&scope=bot%20applications.commands

📊 Monitoring and Logging

Log Files

• bot.log - Main application log
• Console output for real-time monitoring

Health Checks

• Docker health checks included
• Database connectivity monitoring
• Scraper availability testing

Metrics

• Hackathon counts by source
• Scraping success rates
• Notification delivery stats
• Bot uptime and performance

🔒 Security Best Practices

Environment Security

• Never commit .env files to version control
• Use strong, unique MongoDB passwords
• Rotate Discord bot tokens regularly
• Limit bot permissions to minimum required
• Use environment-specific configurations

Docker Security

• Multi-stage builds - Reduces final image size and attack surface
• Non-root user - Runs as dedicated user with UID/GID 1000
• Read-only filesystem - Container filesystem is read-only where possible
• No new privileges - Prevents privilege escalation
• Resource limits - CPU and memory constraints prevent resource exhaustion
• Minimal base image - Uses Python 3.12 slim with security updates
• Secure package installation - Uses --no-install-recommends and proper cleanup
• Updated dependencies - Regular security updates via apt-get upgrade

Alternative Ultra-Secure Deployment

For maximum security, use the distroless image:

# Build with distroless base (no shell, minimal attack surface)
docker build -f Dockerfile.distroless -t hackbot-secure .

# Note: Scraping features require external Chrome setup with distroless

Security Scanning

Regularly scan your images for vulnerabilities:

# Using Docker Scout (built into Docker Desktop)
docker scout cves hackbot

# Using Trivy
trivy image hackbot

# Using Snyk
snyk container test hackbot

• Bot uptime and performance

🔒 Security Best Practices

Environment Security

• Never commit .env files
• Use strong MongoDB passwords
• Rotate bot tokens regularly
• Limit bot permissions

Docker Security

• Runs as non-root user
• Resource limits configured
• Network isolation
• Regular base image updates

🐛 Troubleshooting

Common Issues

Bot not responding to commands:

• Check bot permissions in Discord
• Verify bot token is correct
• Ensure bot is online and ready

Scraping failures:

• Check Chrome/ChromeDriver installation
• Verify headless mode configuration
• Check website accessibility

Database connection issues:

• Verify MongoDB URI format
• Check network connectivity
• Ensure database exists

Memory issues on cloud platforms:

• Reduce scraping frequency
• Limit concurrent operations
• Use smaller Docker base images

Debug Mode

Enable debug logging:

import logging
logging.getLogger().setLevel(logging.DEBUG)

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the existing scraper repository
• Uses discord.py for Discord integration
• MongoDB for data persistence
• Selenium and undetected-chromedriver for web scraping

📞 Support

For issues and questions:

1. Check the troubleshooting section
2. Review logs for error messages
3. Open an issue on GitHub
4. Join our Discord server (if available)

---

Made with ❤️ for the hackathon community