littleshop/TeleBot/MULTI-HOST-DEPLOYMENT.md

🚀 Multi-Host Docker Bot Deployment Guide

Deploy multiple LittleShop TeleBots across different Docker hosts for scalability, redundancy, and geographic distribution.

📋 Table of Contents

• Overview
• Architecture
• Quick Start
• Deployment Methods
• Configuration
• Management
• Security
• Troubleshooting

Overview

The LittleShop TeleBot system supports deploying multiple bot instances across different Docker hosts. Each bot:

• Runs independently in its own container
• Connects to the central LittleShop API
• Has its own Telegram bot token and personality
• Can serve different customer segments or regions

Architecture

┌─────────────────────────────────────────────────┐
│           Central LittleShop API                │
│         (http://api.littleshop.com)             │
└─────────────┬─────────┬─────────┬───────────────┘
              │         │         │
         ┌────▼───┐ ┌──▼───┐ ┌──▼───┐
         │Docker  │ │Docker│ │Docker│
         │Host A  │ │Host B│ │Host C│
         └────────┘ └──────┘ └──────┘
         Support    Sales    VIP Bots
           Bot       Bot

Quick Start

1. Build Docker Image

# Build the image locally
cd /silverlabs/src/LittleShop
docker build -f TeleBot/TeleBot/Dockerfile -t littleshop/telebot:latest .

# Push to registry (Docker Hub, GitLab, or private)
docker push littleshop/telebot:latest

2. Create Bot in Admin Panel

1. Navigate to http://localhost:8080/Admin/Bots/Wizard
2. Follow the wizard to create a bot with @BotFather
3. Save the bot token and API key

3. Deploy Bot

# Using the deployment script
./TeleBot/deploy-bot.sh \
  -n my-bot \
  -t "YOUR_BOT_TOKEN" \
  -k "YOUR_API_KEY" \
  -a "https://api.littleshop.com"

# Or using Docker directly
docker run -d \
  --name littleshop-bot-sales \
  -e Telegram__BotToken=YOUR_TOKEN \
  -e LittleShop__ApiUrl=https://api.shop.com \
  littleshop/telebot:latest

Deployment Methods

Method 1: Deployment Script

The deploy-bot.sh script provides an easy way to deploy bots:

# Deploy to local Docker
./deploy-bot.sh -n support-bot -t "TOKEN" -k "API_KEY"

# Deploy to remote host
./deploy-bot.sh -n sales-bot -t "TOKEN" -h ssh://user@server.com

# Deploy with all options
./deploy-bot.sh \
  -n vip-bot \
  -t "BOT_TOKEN" \
  -k "API_KEY" \
  -a https://api.shop.com \
  -c "ADMIN_CHAT_ID" \
  -e "32_CHAR_ENCRYPTION_KEY" \
  -p "Sarah" \
  -m strict \
  --pull --rm

Method 2: Docker Compose (Multiple Bots)

Deploy multiple bots on the same host:

# Copy and configure environment file
cp .env.multi.example .env.multi
# Edit .env.multi with your values

# Deploy all bots
docker-compose -f docker-compose.multi.yml --env-file .env.multi up -d

# Deploy specific bot
docker-compose -f docker-compose.multi.yml --env-file .env.multi up -d bot-support

# View logs
docker-compose -f docker-compose.multi.yml logs -f

Method 3: Portainer Stack

1. Add Template to Portainer:

   • Go to App Templates → Custom Templates
   • Add the content from portainer-template.json

2. Deploy from Template:

   • Go to App Templates
   • Select "LittleShop TeleBot"
   • Fill in environment variables
   • Deploy

3. Or Deploy Stack Directly:

   curl -X POST \
     http://portainer:9000/api/stacks \
     -H "X-API-Key: YOUR_PORTAINER_KEY" \
     -F "Name=littleshop-bot" \
     -F "StackFileContent=@docker-compose.yml" \
     -F "Env=@.env"
   

Method 4: Docker Swarm

Deploy across a Docker Swarm cluster:

# Initialize swarm (if not already)
docker swarm init

# Create secrets
echo "YOUR_TOKEN" | docker secret create bot_token -
echo "YOUR_API_KEY" | docker secret create bot_api_key -

# Deploy service
docker service create \
  --name littleshop-bot \
  --secret bot_token \
  --secret bot_api_key \
  --replicas 3 \
  --env Telegram__BotToken_FILE=/run/secrets/bot_token \
  --env BotManager__ApiKey_FILE=/run/secrets/bot_api_key \
  littleshop/telebot:latest

Configuration

Environment Variables

Variable	Description	Required
Telegram__BotToken	Bot token from @BotFather	✅
LittleShop__ApiUrl	LittleShop API endpoint	✅
BotManager__ApiKey	API key from admin panel	⭕
Telegram__AdminChatId	Admin notifications chat	⭕
Database__EncryptionKey	32-char encryption key	⭕
Privacy__Mode	strict/moderate/relaxed	⭕

Bot Personalities

Configure different personalities for different bots:

# Support Bot - Helpful and professional
Bot__PersonalityName: "Alan"
Bot__Tone: "professional"

# Sales Bot - Enthusiastic and engaging
Bot__PersonalityName: "Sarah"
Bot__Tone: "friendly"

# VIP Bot - Discrete and sophisticated
Bot__PersonalityName: "Emma"
Bot__Tone: "formal"

Network Configuration

Same Network as API

LittleShop__ApiUrl: http://littleshop-api:8080

Docker Host Network

LittleShop__ApiUrl: http://host.docker.internal:8080

External API

LittleShop__ApiUrl: https://api.littleshop.com

Management

Monitor Bots

# List all bot containers
docker ps --filter "label=com.littleshop.bot=true"

# Check bot health
docker inspect littleshop-bot-support --format='{{.State.Health.Status}}'

# View logs
docker logs -f littleshop-bot-support --tail 100

# Get metrics
docker stats littleshop-bot-support

Update Bots

# Pull latest image
docker pull littleshop/telebot:latest

# Recreate container with new image
docker-compose -f docker-compose.multi.yml pull
docker-compose -f docker-compose.multi.yml up -d

# Or using deployment script
./deploy-bot.sh -n my-bot -t "TOKEN" --pull --rm

Backup & Restore

# Backup bot data
docker run --rm \
  -v littleshop-bot-support-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/bot-backup.tar.gz /data

# Restore bot data
docker run --rm \
  -v littleshop-bot-support-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/bot-backup.tar.gz -C /

Deployment Scenarios

Scenario 1: Geographic Distribution

Deploy bots closer to users for better latency:

# EU Bot on European server
ssh eu-server "docker run -d --name bot-eu \
  -e Telegram__BotToken=$EU_TOKEN \
  -e LittleShop__ApiUrl=https://api.shop.com \
  -e TZ=Europe/London \
  littleshop/telebot:latest"

# US Bot on US server
ssh us-server "docker run -d --name bot-us \
  -e Telegram__BotToken=$US_TOKEN \
  -e LittleShop__ApiUrl=https://api.shop.com \
  -e TZ=America/New_York \
  littleshop/telebot:latest"

# Asia Bot on Singapore server
ssh asia-server "docker run -d --name bot-asia \
  -e Telegram__BotToken=$ASIA_TOKEN \
  -e LittleShop__ApiUrl=https://api.shop.com \
  -e TZ=Asia/Singapore \
  littleshop/telebot:latest"

Scenario 2: Customer Segmentation

Different bots for different customer types:

# docker-compose.segments.yml
services:
  bot-public:
    image: littleshop/telebot:latest
    environment:
      - Privacy__Mode=moderate
      - Features__EnableAnalytics=true

  bot-vip:
    image: littleshop/telebot:latest
    environment:
      - Privacy__Mode=strict
      - Privacy__EnableTor=true
      - Features__EnableOrderMixing=true

  bot-wholesale:
    image: littleshop/telebot:latest
    environment:
      - Features__BulkOrdering=true
      - Features__B2BPricing=true

Scenario 3: A/B Testing

Deploy multiple versions for testing:

# Version A - Standard features
docker run -d --name bot-version-a \
  -e EXPERIMENT_VERSION=A \
  littleshop/telebot:latest

# Version B - New features
docker run -d --name bot-version-b \
  -e EXPERIMENT_VERSION=B \
  -e Features__NewCheckout=true \
  littleshop/telebot:v2-beta

Security

Best Practices

1. Use Docker Secrets for sensitive data:

   echo "TOKEN" | docker secret create bot_token -
   docker service create --secret bot_token ...
   

2. Network Isolation:

   networks:
     frontend:
       driver: overlay
       encrypted: true
     backend:
       driver: overlay
       internal: true
   

3. Resource Limits:

   deploy:
     resources:
       limits:
         cpus: '0.5'
         memory: 512M
   

4. Health Checks:

   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost/health"]
     interval: 30s
     timeout: 10s
     retries: 3
   

TLS/SSL Configuration

For production deployments with TLS:

docker run -d \
  -v /path/to/certs:/certs:ro \
  -e ASPNETCORE_Kestrel__Certificates__Default__Path=/certs/cert.pfx \
  -e ASPNETCORE_Kestrel__Certificates__Default__Password=CERT_PASSWORD \
  -e ASPNETCORE_URLS="https://+:443" \
  littleshop/telebot:latest

Troubleshooting

Common Issues

Bot Won't Start

# Check logs
docker logs littleshop-bot --tail 50

# Common causes:
# - Invalid bot token
# - Can't reach API
# - Port already in use

Can't Connect to API

# Test connectivity from container
docker exec littleshop-bot curl http://api-url/health

# Check DNS resolution
docker exec littleshop-bot nslookup api.shop.com

High Memory Usage

# Check memory stats
docker stats littleshop-bot

# Limit memory
docker update --memory 512m littleshop-bot

Debug Mode

Enable debug logging:

docker run -d \
  -e Logging__LogLevel__Default=Debug \
  -e Logging__LogLevel__TeleBot=Trace \
  littleshop/telebot:latest

Performance Monitoring

# CPU and Memory usage
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# Network I/O
docker exec littleshop-bot netstat -i

# Disk usage
docker system df -v

Advanced Topics

Custom Docker Networks

Create isolated networks for different bot groups:

# Create networks
docker network create bots-support --driver overlay
docker network create bots-sales --driver overlay
docker network create bots-vip --driver overlay --opt encrypted

# Deploy with specific network
docker run -d --network bots-vip ...

Load Balancing

Use multiple bot instances with same token:

# Note: Requires webhook mode and load balancer
docker service create \
  --name bot-pool \
  --replicas 5 \
  --publish 8443:8443 \
  -e Telegram__UseWebhook=true \
  littleshop/telebot:latest

Monitoring with Prometheus

# Add to docker-compose
prometheus:
  image: prom/prometheus
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
  command:
    - '--config.file=/etc/prometheus/prometheus.yml'
  ports:
    - '9090:9090'

Support

For issues or questions:

1. Check container logs: docker logs <container-name>
2. Verify environment variables
3. Test API connectivity
4. Review admin panel bot status
5. Check the main deployment guide

Next Steps

1. Set up monitoring - Add Prometheus/Grafana
2. Implement CI/CD - Automate deployments
3. Add backup strategy - Regular data backups
4. Scale horizontally - Add more hosts as needed
5. Implement geo-routing - Route users to nearest bot