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](#overview)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Deployment Methods](#deployment-methods)
- [Configuration](#configuration)
- [Management](#management)
- [Security](#security)
- [Troubleshooting](#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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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**:
   ```bash
   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:

```bash
# 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:

```yaml
# 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
```yaml
LittleShop__ApiUrl: http://littleshop-api:8080
```

#### Docker Host Network
```yaml
LittleShop__ApiUrl: http://host.docker.internal:8080
```

#### External API
```yaml
LittleShop__ApiUrl: https://api.littleshop.com
```

## Management

### Monitor Bots

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```yaml
# 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:

```bash
# 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:
   ```bash
   echo "TOKEN" | docker secret create bot_token -
   docker service create --secret bot_token ...
   ```

2. **Network Isolation**:
   ```yaml
   networks:
     frontend:
       driver: overlay
       encrypted: true
     backend:
       driver: overlay
       internal: true
   ```

3. **Resource Limits**:
   ```yaml
   deploy:
     resources:
       limits:
         cpus: '0.5'
         memory: 512M
   ```

4. **Health Checks**:
   ```yaml
   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost/health"]
     interval: 30s
     timeout: 10s
     retries: 3
   ```

### TLS/SSL Configuration

For production deployments with TLS:

```bash
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
```bash
# 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
```bash
# 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
```bash
# Check memory stats
docker stats littleshop-bot

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

### Debug Mode

Enable debug logging:

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

### Performance Monitoring

```bash
# 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:

```bash
# 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:

```bash
# 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

```yaml
# 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](DEPLOYMENT.md)

## 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