Ultroid-fork/DOCKER_DEPLOYMENT.md

🐳 Ultroid Docker Deployment Guide (Fork: overspend1/Ultroid-fork)

Complete Docker-based deployment guide for this fork of Ultroid Telegram UserBot. This guide assumes you are building the Docker image from the source code of this repository.

📋 Prerequisites

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

🚀 Recommended Setup: Using ultroid_setup.sh

The easiest and recommended way to deploy this fork using Docker is with the unified setup script:

1. Clone this repository:

   git clone https://github.com/overspend1/Ultroid-fork.git
   cd Ultroid-fork
   

2. Run the setup script:

   bash ultroid_setup.sh
   

   Select the Docker setup option when prompted. The script will guide you through:
   • Checking dependencies (Docker, Docker Compose).
   • Configuring your .env file with necessary variables (API keys, session string, database choice, etc.).
   • Guiding session string generation if needed.
   • Building the Docker image from this fork's source.
   • Starting the Docker containers.

Manually Deploying with Docker Compose (Advanced)

If you prefer a manual approach:

1. Clone This Repository

git clone https://github.com/overspend1/Ultroid-fork.git
cd Ultroid-fork

2. Configure Environment (.env file)

Copy the sample environment file and edit it with your details:

cp .env.sample .env
nano .env # Or your preferred editor

Essential variables to fill:

SESSION=your_session_string_here # See README.md for generation methods
API_ID=your_api_id               # From my.telegram.org/apps
API_HASH=your_api_hash           # From my.telegram.org/apps
# Plus database configuration (see below or .env.sample)

Refer to Necessary Variables in the main README for more details on each variable. Session string can be generated using bash generate-session.sh or other methods.

3. Build and Deploy with Docker Compose

docker-compose build   # Builds the Docker image from this fork's Dockerfile
docker-compose up -d   # Starts the services (bot, database) in detached mode

This uses the Dockerfile and docker-compose.yml present in this repository.

🏗️ 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

• This Fork's Repository: overspend1/Ultroid-fork
• Original Ultroid Support (Telegram): @UltroidSupport (for general Ultroid questions)
• Original Ultroid Documentation: Official Docs (may differ for this fork)
• Session Generator Bot: @SessionGeneratorBot (for generating session strings)

✨ 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!