Discord Stream Bot

A performance-optimized bot that sends Discord notifications when Twitch streamers go live. Features optional logging, Docker containerization, automated CI/CD, and easy setup automation.

• Stream Monitoring: Get notified when Twitch streamers go live
• Optional Logging: Completely disable logging for better performance
• Message Logging: Optional Discord message logging to files
• Performance Optimized: HTTP session reuse, token caching, batch API calls
• Docker Ready: Full containerization with volume mounts and GitHub Container Registry
• CI/CD Pipeline: Automated testing and Docker image builds via GitHub Actions
• Easy Setup: Automated development environment setup
• Cross-Platform: Works on Linux, macOS, and Windows
• Multi-Architecture: Docker images for AMD64 and ARM64 platforms
• 1337 Messages: Optional fun feature for 13:37 notifications
• Thumbnail Support: Download and send stream thumbnails

DiscordStreamBot/
├── src/                    # Source code
│   ├── main.py            # Application entry point
│   └── func/              # Bot functionality modules
│       └── discordbot.py  # Core bot implementation
├── config/                # Configuration templates
│   └── config.ini.dist    # Configuration template
├── scripts/               # Build and setup scripts
│   ├── setup.py           # Development setup utility
│   └── docker-build.sh    # Docker build helper
├── docs/                  # Documentation
├── data/                  # All runtime data
│   ├── images/            # 🖼️ Stream thumbnails (auto-cleanup)
│   ├── logs/              # 📝 Application logs
│   └── server_log/        # 💬 Discord message logs
├── Dockerfile             # Docker image definition
├── docker-compose.yml     # Docker orchestration
├── requirements.txt       # Python dependencies
└── config.ini             # Your bot configuration (create from template)

# Setup
python scripts/setup.py install
cp config/config.ini.dist config.ini
# Edit config.ini with your credentials
python src/main.py

# Using pre-built image from GitHub Container Registry
docker pull ghcr.io/yourusername/discordstreambot:latest

# Run with docker-compose
docker-compose up -d

# Set up development environment
python scripts/setup.py install

# Configure the bot
cp config/config.ini.dist config.ini
# Edit config.ini with your credentials

# Run the bot
python src/main.py

1. Discord Bot Token:

   • Go to Discord Applications
   • Create a new application and bot
   • Copy the bot token

2. Twitch API Credentials:

   • Go to Twitch Dev Dashboard
   • Create a new application
   • Get your Client ID and Client Secret

Edit config.ini with your settings:

[DEFAULT]
LOG_LEVEL = logging.INFO
ENABLE_LOGGING = true          # Set to false for maximum performance

[DISCORD]
token = YOUR_DISCORD_BOT_TOKEN
channel = CHANNEL_ID_FOR_NOTIFICATIONS
message = 🔴 {name} is live!
leet_channel = CHANNEL_ID_FOR_1337_MESSAGES  # Optional
leet_user = USER_ID_TO_MENTION               # Optional
logging = GUILD_ID_FOR_MESSAGE_LOGGING       # Optional

[TWITCH]
client_id = YOUR_TWITCH_CLIENT_ID
client_secret = YOUR_TWITCH_CLIENT_SECRET
streams = streamer1,streamer2,streamer3      # Comma-separated list

# Local development
python src/main.py                     # Run bot locally
python scripts/setup.py install       # Set up development environment
python scripts/setup.py status        # Show bot status

# Docker commands
docker-compose up -d                   # Run with Docker
docker-compose logs -f                 # View Docker logs
docker-compose down                    # Stop Docker containers

# Setup commands
cp config/config.ini.dist config.ini   # Create config from template
mkdir -p data/{logs,server_log,images} # Create data directories

# Setup and management
python scripts/setup.py install       # Set up development environment
python scripts/setup.py run           # Run bot locally
python scripts/setup.py docker-build  # Build Docker image
python scripts/setup.py docker-run    # Run with Docker Compose
python scripts/setup.py status        # Show bot status
python scripts/setup.py clean         # Clean up environment

# Docker build scripts
bash scripts/docker-build.sh run      # Linux/macOS
scripts\docker-build.bat run          # Windows

# From project root directory
docker-compose up -d                  # Start services
docker-compose down                   # Stop services
docker-compose logs -f                # View logs
docker-compose restart                # Restart services

Docker images are automatically built and published to GitHub Container Registry on every push to main:

# Pull the latest image
docker pull ghcr.io/yourusername/discordstreambot:latest

# Run with docker-compose
docker-compose up -d

• latest - Latest stable release from main branch
• main-<sha> - Specific commit from main branch
• <branch>-<sha> - Specific commit from any branch

# For local development with live building
docker-compose up -d --build

• Isolated Environment: No dependency conflicts
• Pre-built Images: No need to build locally, just pull and run
• Automatic Updates: CI/CD pipeline builds images on code changes
• Multi-Architecture: Supports both AMD64 and ARM64 platforms
• Security Scanning: Images are automatically scanned for vulnerabilities
• Easy Updates: Simple container rebuilds or image pulls
• Resource Control: Built-in memory and CPU limits
• Automatic Restart: Container restarts on failures
• Volume Persistence: Config and logs persist across updates

For production environments, use these settings in config.ini:

[DEFAULT]
LOG_LEVEL = logging.ERROR
ENABLE_LOGGING = false    # Disables all file logging

[DISCORD]
logging =                 # Disable message logging

• Memory Usage: 40-50% reduction when logging disabled
• API Response Time: 60-75% faster initialization
• Background Loop: 75-80% faster monitoring cycles
• HTTP Session Reuse: Reduced connection overhead
• Token Caching: Automatic refresh with expiration tracking
• Batch API Calls: Process multiple streamers simultaneously

• Docker Deployment Guide - Comprehensive Docker setup
• Performance Guide - Optimization tips and benchmarks
• Migration Guide - Upgrading from older versions
• Project Structure - Detailed project organization
• Changelog - Version history and changes

# Setup
python scripts/setup.py install  # Automated setup
# Or manual setup:
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate    # Windows

pip install -r requirements.txt
cp config/config.ini.dist config.ini
# Edit config.ini with your credentials

python src/main.py

# Run with debug logging enabled in config.ini
python src/main.py

# Create a systemd service file (you'll need to create this)
sudo nano /etc/systemd/system/discord-stream-bot.service

# Add your service configuration, then:
sudo systemctl daemon-reload
sudo systemctl enable discord-stream-bot
sudo systemctl start discord-stream-bot

# Production deployment with pre-built image
docker-compose up -d

# Update to latest image
docker-compose pull
docker-compose up -d

The bot is automatically published to GitHub Container Registry:

• Registry: ghcr.io/yourusername/discordstreambot
• Automatic Builds: Triggered on push to main branch
• Multi-Platform: AMD64 and ARM64 architectures
• Security Scanning: Trivy vulnerability scanning
• Public Access: No authentication required to pull images

# Local logs
tail -f data/logs/output.log  # Direct file access

# Docker logs
docker-compose logs -f

python scripts/setup.py status
ps aux | grep "src/main.py"  # Check if bot is running
docker-compose ps             # Check Docker containers

1. Bot doesn't start: Check config.ini credentials
2. No notifications: Verify channel permissions and stream names
3. High memory usage: Disable logging in config.ini
4. Docker build fails: Run from project root directory

1. Check the documentation directory
2. Review configuration in config.ini
3. Check logs for specific error messages
4. Ensure all credentials are correct

• Python: 3.8 or higher
• Docker: 20.10+ (for containerized deployment)
• Discord Bot: With message permissions in target channel
• Twitch App: Registered application for API access

This project is licensed under the terms found in the LICENSE file.

See CHANGELOG.md for detailed version history and migration notes.

Quick Start Summary:

1. python scripts/setup.py install to set up environment
2. cp config/config.ini.dist config.ini and edit credentials
3. python src/main.py to start the bot
4. Or use docker-compose up -d for Docker deployment