Ultroid-fork/DOCKER_DEPLOYMENT.md

🐳 Ultroid Docker Deployment Guide

Complete Docker-based deployment guide for Ultroid Telegram UserBot following the official deployment patterns.

📋 Prerequisites

• Docker & Docker Compose installed
• Telegram API credentials (API_ID, API_HASH)
• Session string
• Basic knowledge of environment variables

🚀 Quick Start

1. Clone Repository

git clone https://github.com/TeamUltroid/Ultroid.git
cd Ultroid

2. Generate Session String

chmod +x generate-session.sh
./generate-session.sh

Choose from multiple methods:

• Docker (Recommended)
• Telegram Bot (@SessionGeneratorBot)
• Local Python
• Online Repl.it

3. Configure Environment

cp .env.sample .env
nano .env

Required variables:

SESSION=your_session_string
API_ID=your_api_id
API_HASH=your_api_hash
REDIS_URI=redis://redis:6379
REDIS_PASSWORD=ultroid123

4. Deploy with Docker

chmod +x docker-deploy.sh
./docker-deploy.sh

The script will:

• ✅ Check dependencies
• ✅ Setup environment
• ✅ Configure database
• ✅ Build Docker images
• ✅ Start all services

🏗️ Architecture

Services Included

1. Ultroid Bot - Main userbot service
2. Redis - Primary database (recommended)
3. MongoDB - Alternative database option
4. Session Generator - One-time session creation

Docker Compose Structure

services:
  redis:          # Redis database
  mongodb:        # MongoDB alternative
  ultroid:        # Main bot service
  session-gen:    # Session generator (profile)

📁 Volume Mounts

The following host directories are mounted into the ultroid container. Note that the internal working directory is now /home/ultroid/app.

./downloads          → /home/ultroid/app/downloads
./uploads            → /home/ultroid/app/uploads
./logs               → /home/ultroid/app/logs
./resources/session  → /home/ultroid/app/resources/session
./.env               → /home/ultroid/app/.env (mounted read-only)
./credentials.json   → /home/ultroid/app/credentials.json (if present, mounted read-only)

🔧 Configuration Options

Database Selection

Redis (Recommended)

REDIS_URI=redis://redis:6379
REDIS_PASSWORD=ultroid123

MongoDB Alternative

MONGO_URI=mongodb://ultroid:ultroid123@mongodb:27017/ultroid?authSource=admin

External Database

DATABASE_URL=postgresql://user:pass@host:port/db

Optional Features

# Assistant Bot
BOT_TOKEN=your_bot_token
BOT_MODE=True
DUAL_MODE=True

# Logging
LOG_CHANNEL=your_log_channel_id
OWNER_ID=your_user_id

# Heroku Integration
HEROKU_API_KEY=your_heroku_api
HEROKU_APP_NAME=your_app_name

# Additional APIs
SPAMWATCH_API=your_spamwatch_api
OPENWEATHER_API=your_weather_api
REMOVE_BG_API=your_removebg_api

# Timezone
TZ=Asia/Kolkata  # Example: Europe/London, America/New_York. Sets the container timezone.

🎯 Management Commands

Basic Operations

# View logs
docker-compose logs -f ultroid

# Restart bot
docker-compose restart ultroid

# Stop all services
docker-compose down

# Start services
docker-compose up -d

Updates

# Update bot
git pull
docker-compose build
docker-compose up -d

Maintenance

# Shell access
docker-compose exec ultroid bash # Note: You will be logged in as the 'ultroid' user in /home/ultroid/app

# Database access (Redis)
docker-compose exec redis redis-cli

# Database access (MongoDB)
docker-compose exec mongodb mongo

Backup & Restore

# Backup data
docker-compose exec redis redis-cli --rdb /data/backup.rdb

# View container stats
docker stats

🔍 Troubleshooting

Common Issues

1. Session String Issues

# Regenerate session
./generate-session.sh

2. Database Connection Issues

# Check database status
docker-compose ps # Services should show (healthy) status after startup period
docker-compose logs redis

3. Permission Issues

# Fix permissions
sudo chown -R $USER:$USER downloads uploads logs

4. Plugin Issues

# Check plugin logs
docker-compose logs -f ultroid | grep -i error

Health Checks

# Service status
docker-compose ps

# Resource usage
docker stats ultroid-bot

# Recent logs
docker-compose logs --tail=50 ultroid

🔐 Security Best Practices

Environment Security

# Secure .env file
chmod 600 .env

# Use strong database passwords
REDIS_PASSWORD=generate_strong_password
MONGO_PASSWORD=generate_strong_password

Container Security

# Run as non-root (in production) - Implemented: Bot now runs as non-root 'ultroid' user.
# Use Docker secrets for sensitive data - Consider for advanced setups.
# Regular security updates
docker-compose pull && docker-compose up -d # Pulls latest base images and rebuilds Ultroid

📊 Monitoring & Logs

Log Locations

./logs/                    # Application logs
docker-compose logs        # Container logs

Monitoring

# Real-time logs
docker-compose logs -f ultroid

# Resource monitoring
docker stats

# Service health
docker-compose ps

🚀 Production Deployment

Recommended Setup

# Use external database for production
DATABASE_URL=postgresql://...

# Enable auto-restart
restart: unless-stopped

# Use proper logging
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Scaling

# Multiple bot instances
docker-compose up -d --scale ultroid=2

🔄 Updates & Maintenance

Auto Updates

# Add to crontab
0 6 * * * cd /path/to/Ultroid && git pull && docker-compose build && docker-compose up -d

Manual Updates

# 1. Backup data
docker-compose exec redis redis-cli BGSAVE

# 2. Update code
git pull

# 3. Rebuild and restart
docker-compose build
docker-compose up -d

📞 Support & Resources

• Official Repository: TeamUltroid/Ultroid
• Telegram Support: @UltroidSupport
• Documentation: Official Docs
• Session Generator Bot: @SessionGeneratorBot

✨ Features Included

Core Features

• ✅ All 188+ plugins/addons
• ✅ Google Drive integration
• ✅ Media processing (images, videos, audio)
• ✅ Web scraping capabilities
• ✅ Assistant bot support
• ✅ Database persistence
• ✅ Auto-updates
• ✅ Comprehensive logging

Docker Benefits

• ✅ Isolated environment (now more secure with non-root user)
• ✅ Easy deployment
• ✅ Consistent across platforms
• ✅ Built-in database services (with healthchecks)
• ✅ Volume persistence
• ✅ Health monitoring (via Docker healthchecks and health_check.sh)
• ✅ Easy scaling

---

🎉 Ready for production Docker deployment!