BasharBotV2/DOCKER_DEPLOYMENT.md

Docker Deployment Guide

Quick Start

1. Copy environment file:

   cp .env.example .env
   

2. Edit .env with your Discord token:

   # Edit .env and add your DISCORD_TOKEN
   

3. Build and run with Docker Compose:

   docker-compose up -d
   

4. View logs:

   docker-compose logs -f basharbot
   

Portainer Deployment

Method 1: Using Portainer Stacks

1. Log into Portainer
2. Go to Stacks → Add stack
3. Name it basharbot
4. Choose Upload and upload docker-compose.yml
5. Add environment variables in the Environment variables section:
   • DISCORD_TOKEN: Your Discord bot token
   • WHISPER_MODEL_SIZE: small (or tiny/base/medium/large)
   • LOG_LEVEL: INFO
6. Click Deploy the stack

Method 2: Using Git Repository

1. In Portainer, go to Stacks → Add stack
2. Choose Repository
3. Enter your Git repository URL
4. Set compose path: docker-compose.yml
5. Add environment variables
6. Click Deploy the stack

Configuration

All configuration is done via environment variables in .env:

• DISCORD_TOKEN: Your Discord bot token (required)
• WHISPER_MODEL_SIZE: Model size for speech recognition (tiny/small/base/medium/large)
• LOG_LEVEL: Logging level (DEBUG/INFO/WARNING/ERROR)
• TRANSCRIPT_LOG_ENABLED: Enable transcript logging (true/false)
• HOTWORD_ENABLED: Enable hotword detection (true/false)
• GOODBOY_USER_ID: Special user ID for goodboy audio

Volumes

• ./logs: Bot and transcript logs
• ./data: Persistent data
• whisper-models: Cached Whisper AI models

Commands

# Start the bot
docker-compose up -d

# Stop the bot
docker-compose down

# View logs
docker-compose logs -f

# Restart the bot
docker-compose restart

# Rebuild after code changes
docker-compose up -d --build

# Remove everything including volumes
docker-compose down -v

Troubleshooting

Viewing Portainer Deployment Logs

Option 1: Stack Logs

1. Go to Stacks in Portainer
2. Click on your basharbot stack
3. Look for deployment output at the bottom of the page

Option 2: Container Logs

1. Go to Containers in Portainer
2. Find the basharbot container
3. Click on it and select Logs
4. Use the search/filter to find errors

Option 3: CLI Access

# View deployment logs
docker-compose logs basharbot

# Follow logs in real-time
docker logs -f basharbot

# View last 100 lines
docker logs --tail 100 basharbot

# Check build logs
docker-compose build --no-cache

Common Issues

Build timeout / "No space left on device":

• TTS library is large (~500MB with dependencies)
• Increase Docker build timeout in Portainer
• Or disable Arabic TTS: Set USE_ARABIC_TTS=false in .env

Bot won't start:

• Check logs: docker-compose logs basharbot
• Verify DISCORD_TOKEN is set correctly in .env
• Check for Python import errors in logs

Audio issues:

• Ensure ffmpeg is installed in container (included in Dockerfile)
• Check opus library is available
• Verify voice permissions in Discord

High memory usage:

• Use smaller Whisper model: WHISPER_MODEL_SIZE=tiny
• Disable Arabic TTS: USE_ARABIC_TTS=false
• Reduce model compute type in stt.py

Packet loss warnings:

• These are normal and suppressed in logs
• Don't affect functionality

TTS model download fails:

• First run downloads ~50MB Arabic model
• Ensure container has internet access
• Check /root/.local/share/tts/ volume

Updates

To update the bot:

git pull
docker-compose up -d --build